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894 This document is being jointly developed by the IEEE and The Open Group and is intended to 

895 become both IEEE Std. 1003.1-200x and an Open Group Technical Standard, making up the base 

896 volumes of the Single UNIX Specification, Version 3. 

897 IEEE Std. 1003.1-200x 

898 IEEE Std. 1003.1-200x defines the Portable Operating System Interface (POSIX) requirements and 

899 consists of the following volumes: 

900 • System Interface Definitions 

901 • Commands and Utilities 

902 • System Interfaces (this volume) 


903 This volume of IEEE Std. 1003.1-200x 

904 The System Interfaces volume of IEEE Std. 1003.1-200x describes the interfaces offered to 

905 application programs by POSIX-conformant systems. Readers are expected to be experienced C 

906 language programmers, and to be familiar with the System Interface Definitions volume of 

907 IEEE Std. 1003.1-200x. 

908 This volume of IEEE Std. 1003.1-200x is structured as follows: 


909 • Chapter 1 explains the status of this volume of IEEE Std. 1003.1-200x and its relationship to 

910 other formal standards. 


911 • Chapter 2 contains important concepts, terms, and caveats relating to the rest of this volume 

912 of IEEE Std. 1003.1-200x. 


913 • Chapter 3 defines the functional interfaces to the POSIX-conformant system. 

914 Comprehensive references are available in the index. 


915 Typographical Conventions 

916 The following typographical conventions are used throughout IEEE Std. 1003.1-200x: 

917 • Bold font is used in text for options to commands, file names, keywords, type names, data 

918 structures, and their members. 

919 • Italic strings are used for emphasis or to identify the first instance of a word requiring 

920 definition. Italics in text also denote: 

921 — Command operands, command option-arguments, or variable names; for example, 

922 substitutable argument prototypes 

923 — Environment variables, which are also shown in capitals 

924 — Utility names 

925 — External variables, such as errno 

926 — Functions; these are shown as follows: name( ); names without parentheses are C external 

927 variables, C function family names, utility names, command operands, or command 

928 option-arguments. 
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• Normal font is used for the names of constants and literals. 

• The notation <file.h> indicates a header. 

• Names surrounded by braces, for example, {ARG_MAX}, represent symbolic limits or 
configuration values which may be declared in appropriate headers by means of the C 
#define construct. 

• The notation [EABCD] is used to identify an error value EABCD. 

• Syntax, code examples, and user input in interactive examples are shown in fixed width 
font. Brackets shown in this font, [ ], are part of the syntax and do not indicate optional 
items. In syntax the I symbol is used to separate alternatives, and ellipses (...) are used to 
show that additional arguments are optional. 

• Bold fixed width font is used to identify brackets that surround optional items in syntax, 
[ ], and to identify system output in interactive examples. 

• Variables within syntax statements are shown in italic fixed width font. 

• Ranges of values are indicated with parentheses or brackets as follows: 

— (a,b) means the range of all values from a to b, including neither a nor b. 

— [a,b] means the range of all values from a to b, including a and b. 

— [ a,b ) means the range of all values from a to b, including a, but not b. 

— ( a,b ] means the range of all values from a to b, including b, but not a. 

• Shading is used to identify extensions or warnings. 

Notes: 
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1. Symbolic limits are used in this volume of IEEEStd. 1003.1-200x instead of 
fixed values for portability. The values of most of these constants are defined in 
the System Interface Definitions volume of IEEE Std. 1003.1-200x, <limits.h> or 
<unistd.h>. 
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2. The values of errors are defined in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <errno.h>. 
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Scope 

This volume of IEEE Std. 1003.1-200x defines a standard operating system interface and 
environment to support applications portability at the source-code level. It is intended to be 
used by both applications developers and system implementors. The System Interface 
Definitions volume of IEEE Std. 1003.1-200x defines general terms, concepts, and interfaces used 
by this volume of IEEE Std. 1003.1-200x. 

This volume of IEEE Std. 1003.1-200x comprises three major components: 

1. Definitions for system service functions and subroutines 

2. Language-specific system services for the C programming language 

3. Function issues, including portability, error handling, and error recovery 


12 The following areas are outside of the scope of this volume of IEEE Std. 1003.1-200x: 


13 

14 

15 

16 

17 

18 


1. User interface (shell) and associated commands 

2. Graphics interfaces 

3. Database management system interfaces 

4. Record I/O considerations 

5. Object or binary code portability 

6. System configuration and resource availability 


19 This volume of IEEE Std. 1003.1-200x describes the external characteristics and facilities that are 

20 of importance to applications developers, rather than the internal construction techniques 

21 employed to achieve these capabilities. Special emphasis is placed on those functions and 

22 facilities that are needed in a wide variety of commercial applications and applications with 

23 realtime requirements. 


24 The functions included to address commercial applications include the set of UNIX system 

25 interfaces from The Open Group specifications. A requirement on the integration of this material 

26 is to maximize backwards-compatibility with existing specifications. 


27 The functions included to address realtime requirements are the set required to make 

28 IEEE Std. 1003.1-200x minimally usable to realtime applications on single processor systems. The 

29 definition of realtime used in defining the scope of this volume of IEEE Std. 1003.1-200x is as 

30 follows: 


31 Realtime in operating systems: the ability of the operating system to provide a required level 

32 of service in a bounded response time. 


33 This volume of IEEE Std. 1003.1-200x includes functions to support applications with 

34 requirements for multiple flows of control, called threads, within a process. The facilities 

35 provided support a convenient function for writing multi-threaded applications. 


36 


The key elements defining the scope are as follows: 
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37 1. Defining a sufficient set of functionality to cover a significant part of the realtime 

38 application program domain 

39 2. Defining sufficient performance constraints and performance-related functions to allow a 

40 realtime application to achieve deterministic response from the system 

41 3. Defining a sufficient set of functionality to support multiple threads of control within a 

42 process 

43 Specifically within the scope is to define functions that do not preclude high-performance 

44 implementations on traditional uniprocessor realtime systems. The functions in this volume of 

45 IEEE Std. 1003.1-200x are specifically targeted at supporting tightly coupled multitasking 

46 environments, including multiprocessors and advanced language constructs. Wherever possible, 

47 the requirements of other application environments are included in this function definition. It is 

48 beyond the scope of these functions to support networking functionality. 

49 This volume of IEEE Std. 1003.1-200x has been defined exclusively at the source-code level. The I 

50 objective is that a Strictly Conforming POSIX Application source program can be translated to 

51 execute on a conforming implementation. Additionally, although the functions are portable, 

52 some of the numeric parameters used by an implementation may have hardware dependencies. 
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53 1. 

54 

55 


Conformance 

Conformance requirements for IEEE Std. 1003.1-200x are defined in the System Interface 
Definitions volume of IEEE Std. 1003.1-200x, Chapter 2, Conformance. 
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56 1.3 Normative References 

57 Notes to Reviewers 

58 This section with side shading will not appear in the final copy. - Ed. 

59 The list of standards to be revised. 

60 The following standards contain provisions which, through references in this text, constitute 

61 provisions of this volume of IEEE Std. 1003.1-200x. At the time of publication, the editions 

62 indicated were valid. All standards are subject to revision, and parties to agreements based on 

63 This volume of IEEE Std. 1003.1-200x are encouraged to investigate the possibility of applying 

64 the most recent editions of the standards listed below. Members of IEC and ISO maintain 

65 registers of currently valid International Standards. 

66 ISO/IEC 646 

67 ISO/IEC 646:1991, Information Processing — ISO 7-bit Coded Character Set for Information 

68 Interchange. 1 

69 ISO/IEC 9899 

70 ISO/IEC 9899:1990, Programming Languages — C. 

71 ISO/IEC 9945-2 

72 ISO/IEC 9945-2:1993, Information Technology — Portable Operating System Interface 

73 (POSIX) — Part 2: Shell and Utilities. 

74 ISO/IEC 10646-1 

75 ISO/IEC 10646-1:1993, Information Technology — Universal Multiple-Octet Coded 

76 Character Set (UCS) — Part 1: Architecture and Basic Multilingual Plane. 

77 ISO/IEC 14519:1999 

78 ISO/IEC 14519:1999, Information Technology — POSIX Ada Language Interfaces — 

79 Binding for System Application Program Interface (API) — Realtime Extensions. 


80 - 

81 1. ISO/IEC documents can be obtained from the ISO office: 1 Rue de Varembe, Case Postale 56, CH-1211, Geneve 20, 

82 Switzerland/Suisse 
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83 1.4 Changes from Issue 4 

84 Notes to Reviewers 

85 This section with side shading will not appear in the final copy. - Ed. 

86 The change history is subject to revision. The intent is to document changes from Issue 4 thru 

87 Issue 6, with the latest change history also documenting changes from the ISO POSIX-1:1996 

88 standard. 


89 

90 

91 

92 


The following sections describe changes made to this volume of IEEE Std. 1003.1-200x since 
Issue 4. The CHANGE HISTORY section for each entry details the technical changes that have 
been made to that entry since Issue 4. Changes made between Issue 2 and Issue 4 are not 
included. 


93 1.4.1 Changes from Issue 4 to Issue 4, Version 2 

94 The following list summarizes the major changes that were made in this volume of 

95 IEEE Std. 1003.1-200x from Issue 4 to Issue 4, Version 2: 

96 • The X/Open UNIX extension was added. This specifies the common core APIs of 4.3 

97 Berkeley Software Distribution (BSD 4.3), the OSF AES, and SVID Issue 3. 

98 • STREAMS were added as part of the X / Open UNIX extension. 

99 • Existing Issue 4 functions were clarified as a result of industry feedback. 


100 1.4.2 

101 
102 

103 

104 

105 

106 

107 

108 

109 

110 

111 

112 

113 

114 

115 

116 


Changes from Issue 4, Version 2 to Issue 5 

The following list summarizes the major changes that were made in this volume of 
IEEE Std. 1003.1-200x from Issue 4, Version 2 to Issue 5: 

• Functions previously defined in the ISO POSIX-2 standard C-language Binding, Shared 
Memory, Enhanced Internationalization, and X/Open UNIX Extension Feature Groups were 
moved to the BASE. 

• Threads were added to the BASE for alignment with the POSIX Threads Extension. 

• The Realtime Threads Feature Group was added. 

• The Realtime Feature Group was added for alignment with the POSIX Realtime Extension. 

• Multibyte Support Extensions (MSE) were added to the BASE for alignment with 
ISO/IEC 9899:1990/Amendment 1:1995 (E). 

• Large File Summit (LFS) Extensions were added to the BASE for support of 64-bit or larger 
files and file systems. 

• X/Open-specific threads extensions were added to the BASE. 

• X/Open-specific dynamic linking functions were added to the BASE. 

• A new category Legacy was added. 

• The categories TO BE WITHDRAWN and WITHDRAWN were removed. 
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117 1.4.3 Changes from Issue 5 to Issue 6 (IEEE Std. 1003.1-200x) 

118 The following list summarizes the major changes that were made in this volume of 

119 IEEE Std. 1003.1-200x from Issue 5 to Issue 6: 

120 • This volume of IEEE Std. 1003.1-200x is extensively revised so it can be both an IEEE POSIX 

121 Standard and an Open Group Technical Standard. 

122 • The POSIX System Interfaces requirements incorporate support of FIPS 151-2. 

123 • The POSIX System Interfaces requirements are updated to align with some features of the 

124 Single UNIX Specification. 

125 • A RATIONALE section is added to each reference page. 

126 • A new chapter on Portability Considerations is added. 
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1.5 New Features 

1.5.1 New Features in Issue 4, Version 2 

The functions, headers, and external variables first introduced in Issue 4, Version 2 are listed in 
the table below. 


New Functions, Headers, and External Variables in Issue 4, Version 2 

FD_CLR() 

endutxent() 

gettimeofday () 

ptkname () 

si/altstack () 

FD_ISSET() 

exftml () 

getutxent {) 

piltmsg () 

si/hold() 

FD_SET() 

/attach () 

getutxid () 

piltpmsg {) 

si/ignore{) 

FD_ZERO() 

fcMir () 

getutxline() 

piltutxline() 

si/interrnpt() 

Jongjmp () 

fchmod () 

getzvd () 

rahdom () 

si/panse{) 

_setjmp () 

fchoivn () 

grhntpt() 

re\_comp () 

si/relse{) 

a641 () 

fcM() 

ildgb () 

reJ_ejec() 

si&set () 

acosh () 

fdktacli () 

index {) 

rekdlink() 

si£stack() 

asinh () 

M) 

inltstate () 

rekdzi () 

srkndom () 

atanh () 

fnitmsg() 

inkque() 

reklpath () 

stbtzfs () 

basename() 

fstatvfs () 

ioitl () 

re/cmp () 

stkcasecmp () 

bcmp () 

ftiine () 

isdstream() 

re£ex() 

sttdupO 

bcopy () 

ftdkO 

killpg () 

rebiainder () 

stkncasecmp () 

brk () 

/truncate () 

Z64«() 

retnque () 

szbapcontext () 

bsd_signal () 

gcbt() 

Ichozvn () 

riMex () 

sytnlink() 

feero() 

get context () 

loikf () 

rM() 

syhc() 

cbrt() 

get date () 

Hip 0 

sbtk () 

syblogO 

closelog() 

getdtablesize () 

/<#() 

scklb() 

tc/etsid () 

dbm_clearerr () 

getgrent() 

lsht() 

select () 

triincate () 

dbm_close() 

gethostid () 

mtike context () 

s eicontext () 

tt/slot () 

dbm_delete{) 

getitimeri ) 

mknod () 

s etgrent() 

udlarm () 

dbm_error() 

getmsg() 

mkstempi) 

selitimeri ) 

in\lockpt{) 

dbm_fetch () 

getpagesize () 

mktemp () 

seilogmask() 

nsteep() 

dbmjirstkey () 

getpgid() 

minap () 

setpgrp() 

ntimes () 

dbm_nextkey() 

getpmsg () 

mprotect() 

seipriority () 

vatloc() 

dbm_open () 

getpriority () 

miync() 

seipzvent() 

zfbrk () 

dbm_store () 

getpzvent() 

miinmapO 

setregid() 

zvtiit3 () 

dirname () 

getrlimit() 

ndxtafter () 

seireuid() 

zvtlitid () 

ecvt() 

getrusage{) 

nflzv() 

setrlimit() 

zvkitev () 

endgrent () 

getsid() 

openlog() 

setstate () 

1 

endpzvent() 

getsubopt () 

potl () 

sehitxenti ) 

1 

<fmtmsg.h> 

<rte_comp.h> 

<slys/resource.h> <slys/uio.h> 

<iltmpx.h> 

<libgen.h> 

<sltrings.h> 

<slys/statvfs.h> 

<slys/un.h> 

1 

<ndbm.h> 

<sltropts.h> 

<slys/time.h> 

<slyslog.h> 

1 

<poll.h> 

getdate_err 

<slys/mman.h> 

_ loci 

<slys/timeb.h> 

<itcontext.h> 

1 


System Interfaces, Issue 6 


7 






New Features 


Introduction 


169 1.5.2 New Features in Issue 5 


170 The functions and headers first introduced in Issue 5 are listed in the table below. 

171 


172 

New Functions and Headers in Issue 5 

173 

aio_cancel () 

pthread_attr_getstacksize() 

pthread_self() 

174 

aio_error () 

pthread_attr_init() 

pthread_setcancelstate() 

175 

aiojsync () 

pthread_attr_setdetachstate () 

pthread_setcanceltype() 

176 

aio_read () 

pthread_attr_setguardsize{) 

pthread_set concurrency () 

177 

aiojeturn() 

pthread_attr_setinheritsched () 

pthread_setschedparam () 

178 

aio_suspend() 

pthread_attr_setschedparam() 

pthread_setspecific() 

179 

aio_write{) 

pthread_attr_setschedpolicy () 

pthread_sigmask() 

180 

asctime_r() 

pthread_attr_setscope() 

pthread_testcancel () 

181 

btowc() 

pthread_attr_setstackaddr() 

putcjinlocked() 

182 

clock_getres () 

pthread_attr_setstacksize() 

putcharjinlocked() 

183 

dock_gettime () 

pthread_cancel() 

pwrite{) 

184 

clock_settime () 

pthread_cleanup_pop() 

rand_r() 

185 

ctime_r () 

pthread_cleanup_push () 

readdir_r () 

186 

diclose () 

pthread_cond_broadcast() 

sched_get_priority_max() 

187 

dlerror () 

pthread_cond_destroy{) 

sched_get jpriorityjnin () 

188 

dlopen () 

pthread_cond_init () 

sched_getparam () 

189 

dlsym() 

pthread_cond_signal() 

sched_getsckeduler() 

190 

fdatasync() 

pthread_cond_timedwait{) 

sched_rr_get_interval() 

191 

flockfile () 

pthread_cond_zvait() 

scked_setparam() 

192 

fseeko() 

pthread_condattr_destroy() 

sched_setscheduler () 

193 

ftello () 

pthread_condattr_getpshared() 

sched_yield () 

194 

ftrylockfile () 

pthread_condattr_init () 

sem_close() 

195 

funlockfile () 

pthread_condattr_setpshared() 

sem_destroy() 

196 

ftvide() 

pthread_create() 

sem_getvalue{) 

197 

fivprintf () 

pthread_detach () 

sem_init() 

198 

ftvscanf() 

pthread_equal() 

semjopen () 

199 

getcjinlocked () 

pthread_exit () 

sem_post() 

200 

getclmr_unlocked () 

pthread_getconcurrency() 

sem_trywait () 

201 

getgrgid_r() 

pthread_getschedparam() 

semjmlinki) 

202 

getgrnam_r () 

pthread_getspecific() 

semjuaiti) 

203 

getlogin_r() 

pthread_join () 

shmjopen () 

204 

getpivnam_r () 

pthread_key_create() 

shmjmlink() 

205 

getpwidd_r() 

pthread_key_delete() 

sigqueue() 

206 

gmtime_r () 

pthreadjdll () 

sigtimedwait () 

207 

lio_listio () 

pthread_mutex_destroy() 

sigzvait() 

208 

localtime_r () 

pth read_mutex_getprioceil ing() 

sigzvaitinfo () 

209 

mbrlen () 

pthread_mutex_init () 

snprintf() 

210 

mbrtowc {) 

pthread_mutex_lock() 

strtokj'() 

211 

mbsinit() 

pth read_mutex_setprioceil ing() 

szvprintf() 

212 

mbsrtowcs () 

pthread_mutex_trylock() 

szvscanf() 

213 

mlock() 

pthread_mutex_unlock() 

timer_create () 

214 

mlockall () 

ptkreadjnutexattr_destroy {) 

timer_delete{) 

215 

mq_close() 

ptkreadjnutexattr_getprioceiling() timer_getoverrun () 

216 

mq_getattr () 

ptkreadjnutexattr_getprotocol () 

timer_gettime() 

217 

mq_notify () 

ptkreadjnutexattr_getpshared () 

timer_settime() 

218 

mq_open () 

pthreadjnutexattr_gettype() 

tozvctrans () 
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219 


220 

New Functions and Headers in Issue 5 

221 

mq_receive () 

pthreadjnu texattr_ini t () 

ttyname_r () 

222 

mq_send () 

pthread_mutexattr_setprioceiling () vfwprintf () 

223 

mq_setattr () 

pthread_mntexattr_setprotocol () 

vsnprintf () 

224 

mq_unlink () 

pthread_mutexattr_setpshared () 

vszvprintf () 

225 

nmnlock () 

ptkread_mutexattr_settype{) 

vwprintf{) 

226 

munlockall () 

pthread_once () 

wcrtomb () 

227 

nanosleep () 

ptkread_rivlock_destroy () 

wcsrtombs () 

228 

pread () 

pthread_nvlock_init () 

zvcsstr() 

229 

pthread_atfork () 

pthread_nvlock_rdlock() 

zvctob () 

230 

pthread_attr_destroy () 

pthread_nvlock_tryrdlock () 

zvctrans () 

231 

pthread_attr_getdetachstate () 

pthread_rwlock_trywrlock () 

zumemchri ) 

232 

pthread_attr_getgnardsize() 

pthread_nvlock_unlock () 

zumemcmpi ) 

233 

pthread_attr_getinheritsched () 

pthread_rwlock_wrlock () 

zvmemcpy () 

234 

pthread_attr_getschedparam () 

pthread_rzvlockattr_destroy{) 

zumemmovei ) 

235 

pthread_attr_getschedpolicy () 

pthread_rwlockattr_getpshared () 

zumemseti ) 

236 

pthread_attr_getscope () 

pthread_nvlockattr_init () 

zvprintf () 

237 

pthread_attr_getstackaddr () 

pthread_rwlockattr_setpshared () 

zvscanf() 

238 

<aio.h> 

<iso646.h> 

<sched.h> 

239 

<dlfcn.h> 

<mqueue.h> 

<semaphore.h> 

240 

<inttypes.h> 

<pthread.h> 

<wctype.h> 
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241 1.5.3 New Features in Issue 6 

242 Notes to Reviewers 

243 This section with side shading will not appear in the final copy. - Ed. 

244 A table listing new functions, headers, etc. since the ISO POSIX-1:1996 standard will be added 

245 here in a future draft. 
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246 1.6 Terminology 

247 This section appears in the System Interface Definitions volume of IEEE Std. 1003.1-200x, but is 

248 repeated here for convenience: 

249 For the purposes of IEEE Std. 1003.1-200x, the following terminology definitions apply: 


250 can 

251 Describes a permissible optional feature or behavior available to the user or application. The 

252 feature or behavior is mandatory for an implementation that conforms to 

253 IEEE Std. 1003.1-200x. An application can rely on the existence of the feature or behavior. 


254 

255 

256 

257 

258 

259 


implementation-dependent 

(Same meaning as implementation-defined.) Describes a value or behavior that is not defined 
by IEEE Std. 1003.1-200x but is selected by an implementor. The value or behavior may vary 
among implementations that conform to IEEE Std. 1003.1-200x. An application should not 
rely on the existence of the value or behavior. An application that relies on such a value or 
behavior cannot be assured to be portable across conforming implementations. 


260 The implementor shall document such a value or behavior so that it can be used correctly 

261 by an application. 


262 

263 

264 

265 

266 


legacy 

Describes a feature or behavior that is being retained for compatibility with older 
applications, but which has limitations which make it inappropriate for developing portable 
applications. New applications should use alternative means of obtaining equivalent 
functionality. 


267 

268 

269 

270 

271 


may 

Describes a feature or behavior that is optional for an implementation that conforms to 
IEEE Std. 1003.1-200x. An application should not rely on the existence of the feature or 
behavior. An application that relies on such a feature or behavior cannot be assured to be 
portable across conforming implementations. 


272 


To avoid ambiguity, the opposite of may is expressed as need not, instead of may not. 


273 shall 

274 For an implementation that conforms to IEEE Std. 1003.1-200x, describes a feature or 

275 behavior that is mandatory. An application can rely on the existence of the feature or 

276 behavior. 


277 


For an application or user, describes a behavior that is mandatory. 


278 

279 

280 
281 
282 


should 

For an implementation that conforms to IEEE Std. 1003.1-200x, describes a feature or 
behavior that is recommended but not mandatory. An application should not rely on the 
existence of the feature or behavior. An application that relies on such a feature or behavior 
cannot be assured to be portable across conforming implementations. 


283 For an application, describes a feature or behavior that is recommended programming 

284 practice for optimum portability. 


285 undefined 

286 Describes the nature of a value or behavior not defined by IEEE Std. 1003.1-200x which 

287 results from use of an invalid program construct or invalid data input. 


288 The value or behavior may vary among implementations that conform to 

289 IEEE Std. 1003.1-200x. An application should not rely on the existence or validity of the 

290 value or behavior. An application that relies on any particular value or behavior cannot be 
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291 assured to be portable across conforming implementations. 

292 unspecified 

293 Describes the nature of a value or behavior not specified by IEEE Std. 1003.1-200x which 

294 results from use of a valid program construct or valid data input. 

295 The value or behavior may vary among implementations that conform to 

296 IEEE Std. 1003.1-200x. An application should not rely on the existence or validity of the 

297 value or behavior. An application that relies on any particular value or behavior cannot be 

298 assured to be portable across conforming implementations. 

299 will 

300 Same meaning as shall-, shall is the preferred term. 
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301 1.7 Definitions 

302 Concepts and definitions are defined in the System Interface Definitions volume of 

303 IEEE Std. 1003.1-200x. 
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304 1.8 Relationship to Other Formal Standards 

305 Great care has been taken to ensure that this volume of IEEE Std. 1003.1-200x is fully aligned 

306 with the following standards: 

307 ISO/IEC 9899 

308 ISO/IEC 9899:1990, Programming Languages — C. 

309 Parts of ISO/IEC 9899 (hereinafter referred to as the ISO C standard) are referenced to describe 

310 requirements also mandated by this volume of IEEE Std. 1003.1-200x. Some functions and 

311 headers included within this volume of IEEE Std. 1003.1-200x have a version in the ISO C 

312 standard; in this case CX markings are added as appropriate to show where the ISO C standard 

313 has been extended. Any conflict between this volume of IEEE Std. 1003.1-200x and the ISO C 

314 standard is unintentional. 

315 This volume of IEEE Std. 1003.1-200x also allows, but does not require, mathematics functions to 

316 support the IEEE Std. 754:1985 standard and the IEEE Std. 854:1987 standard. 
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317 1.9 Portability 

318 Some of the utilities in the Commands and Utilities volume of IEEE Std. 1003.1-200x and 

319 functions in the System Interfaces volume of IEEE Std. 1003.1-200x describe functionality that 

320 might not be fully portable to systems meeting the requirements for POSIX conformance (see the 

321 System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 2, Conformance). 

322 Where optional, enhanced, or reduced functionality is specified, the text is shaded and a code in 

323 the margin identifies the nature of the option, extension, or warning (see Section 1.9.1). For 

324 maximum portability, an application should avoid such functionality. 

325 1.9.1 Codes 

326 Margin codes and their meanings are listed in the System Interface Definitions volume of 

327 IEEE Std. 1003.1-200x, but are repeated here for convenience: 

328 adv Advisory Information 

329 The functionality described is optional. The functionality described is also an extension to the 

330 ISO C standard. 

331 Where applicable, functions are marked with the ADV margin legend in the SYNOPSIS section. 

332 Where additional semantics apply to a function, the material is identified by use of the ADV 

333 margin legend. 

334 aio Asynchronous Input and Output 

335 The functionality described is optional. The functionality described is also an extension to the 

336 ISO C standard. 

337 Where applicable, functions are marked with the AIO margin legend in the SYNOPSIS section. 

338 Where additional semantics apply to a function, the material is identified by use of the AIO 

339 margin legend. 

340 bar Barriers 

341 The functionality described is optional. The functionality described is also an extension to the 

342 ISO C standard. 

343 Where applicable, functions are marked with the BAR margin legend in the SYNOPSIS section. 

344 Where additional semantics apply to a function, the material is identified by use of the BAR 

345 margin legend. 

346 be Batch Environment Services and Utilities 

347 The functionality described is optional. 

348 Where applicable, utilities are marked with the BE margin legend in the SYNOPSIS section. 

349 Where additional semantics apply to a utility, the material is identified by use of the BE margin 

350 legend. 

351 cd C-Language Development Utilities 

352 The functionality described is optional. 

353 Where applicable, utilities are marked with the CD margin legend in the SYNOPSIS section. 

354 Where additional semantics apply to a utility, the material is identified by use of the CD margin 

355 legend. 

356 cpt Process CPU-Time Clocks 

357 The functionality described is optional. The functionality described is also an extension to the 

358 ISO C standard. 

359 Where applicable, functions are marked with the CPT margin legend in the SYNOPSIS section. 

360 Where additional semantics apply to a function, the material is identified by use of the CPT 
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361 margin legend. 

362 cs Clock Selection 

363 The functionality described is optional. The functionality described is also an extension to the 

364 ISO C standard. 

365 Where applicable, functions are marked with the CS margin legend in the SYNOPSIS section. 

366 Where additional semantics apply to a function, the material is identified by use of the CS 

367 margin legend. 

368 cx Extension to the ISO C standard 

369 The functionality described is an extension to the ISO C standard. Application writers may 

370 confidently make use of an extension as it is supported on all IEEE Std. 1003.1-200x conforming 

371 systems. 

372 fd FORTRAN Development Utilities 

373 The functionality described is optional. 

374 Where applicable, utilities are marked with the FD margin legend in the SYNOPSIS section. 

375 Where additional semantics apply to a utility, the material is identified by use of the FD margin 

376 legend. 

377 fr FORTRAN Runtime Utilities 

378 The functionality described is optional. 

379 Where applicable, utilities are marked with the FR margin legend in the SYNOPSIS section. 

380 Where additional semantics apply to a utility, the material is identified by use of the FR margin 

381 legend. 

382 fsc File Synchronization 

383 The functionality described is optional. The functionality described is also an extension to the 

384 ISO C standard. 

385 Where applicable, functions are marked with the FSC margin legend in the SYNOPSIS section. 

386 Where additional semantics apply to a function, the material is identified by use of the FSC 

387 margin legend. 

388 IP6 IPV6 

389 The functionality described is optional. The functionality described is also an extension to the 

390 ISO C standard. 

391 Where applicable, functions are marked with the IP6 margin legend in the SYNOPSIS section. 

392 Where additional semantics apply to a function, the material is identified by use of the IP6 

393 margin legend. 

394 man Mandatory in the Next Draft 

395 This is an interim draft code used to aid reviewers during the development of 

396 IEEE Std. 1003.1-200x. It denotes a feature that was previously an option or extension that is 

397 being brought into the mandatory base functionality. This margin code will be removed from the 

398 final draft. 

399 mf Memory Mapped Files 

400 The functionality described is optional. The functionality described is also an extension to the 

401 ISO C standard. 

402 Where applicable, functions are marked with the MF margin legend in the SYNOPSIS section. 

403 Where additional semantics apply to a function, the material is identified by use of the MF 

404 margin legend. 
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405 ml Process Memory Locking 

406 The functionality described is optional. The functionality described is also an extension to the 

407 ISO C standard. 

408 Where applicable, functions are marked with the ML margin legend in the SYNOPSIS section. 

409 Where additional semantics apply to a function, the material is identified by use of the ML 

410 margin legend. 

411 mlr Range Memory Locking 

412 The functionality described is optional. The functionality described is also an extension to the 

413 ISO C standard. 

414 Where applicable, functions are marked with the MLR margin legend in the SYNOPSIS section. 

415 Where additional semantics apply to a function, the material is identified by use of the MLR 

416 margin legend. 

417 mon Monotonic Clock 

418 The functionality described is optional. The functionality described is also an extension to the 

419 ISO C standard. 

420 Where applicable, functions are marked with the MON margin legend in the SYNOPSIS section. 

421 Where additional semantics apply to a function, the material is identified by use of the MON 

422 margin legend. 

423 mpr Memory Protection 

424 The functionality described is optional. The functionality described is also an extension to the 

425 ISO C standard. 

426 Where applicable, functions are marked with the MPR margin legend in the SYNOPSIS section. 

427 Where additional semantics apply to a function, the material is identified by use of the MPR 

428 margin legend. 

429 msg Message Passing 

430 The functionality described is optional. The functionality described is also an extension to the 

431 ISO C standard. 

432 Where applicable, functions are marked with the MSG margin legend in the SYNOPSIS section. 

433 Where additional semantics apply to a function, the material is identified by use of the MSG 

434 margin legend. 

435 ob Obsolescent 

436 The functionality described may be withdrawn in a future version of this volume of 

437 IEEE Std. 1003.1-200x. Strictly Conforming POSIX Applications and Strictly Conforming XSI 

438 Applications shall not use obsolescent features. 

439 of Output Format Incompletely Specified 

440 The functionality described is an XSI extension. The format of the output produced by the utility 

441 is not fully specified. It is therefore not possible to post-process this output in a consistent 

442 fashion. Typical problems include unknown length of strings and unspecified field delimiters. 

443 oh Optional Header 

444 In the SYNOPSIS section of some interfaces in the System Interfaces volume of 

445 IEEE Std. 1003.1-200x an included header is marked as in the following example: 

446 OH #include <sys/types .h> 

447 #include <grp.h> 

448 struct group *getgrnam(const char *name); 
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449 This indicates that the marked header is not required on XSI-conformant systems. 

450 pi The Behavior Cannot be Guaranteed to be Consistent 

451 The functionality described is an XSI extension. It is not possible to guarantee that the utility 

452 behaves in the same way on all conformant systems. This is the case if it provides functionality 

453 that is implementation-dependent. Options that are used to select alternative forms of 

454 implementation-dependent behavior are not marked, as it is clear from their descriptions that 

455 their use is inherently non-portable. 

456 pio Prioritized Input and Output 

457 The functionality described is optional. The functionality described is also an extension to the 

458 ISO C standard. 

459 Where applicable, functions are marked with the PIO margin legend in the SYNOPSIS section. 

460 Where additional semantics apply to a function, the material is identified by use of the PIO 

461 margin legend. 

462 ps Process Scheduling 

463 The functionality described is optional. The functionality described is also an extension to the 

464 ISO C standard. 

465 Where applicable, functions are marked with the PS margin legend in the SYNOPSIS section. 

466 Where additional semantics apply to a function, the material is identified by use of the PS 

467 margin legend. 

468 rts Realtime Signals Extension 

469 The functionality described is optional. The functionality described is also an extension to the 

470 ISO C standard. 

471 Where applicable, functions are marked with the RTS margin legend in the SYNOPSIS section. 

472 Where additional semantics apply to a function, the material is identified by use of the RTS 

473 margin legend. 

474 rwl Reader/Writer Locks 

475 The functionality described is optional. The functionality described is also an extension to the 

476 ISO C standard. 

477 Where applicable, functions are marked with the RWL margin legend in the SYNOPSIS section. 

478 Where additional semantics apply to a function, the material is identified by use of the RWL 

479 margin legend. 

480 sd Software Development Utilities 

481 The functionality described is optional. 

482 Where applicable, utilities are marked with the SD margin legend in the SYNOPSIS section. 

483 Where additional semantics apply to a utility, the material is identified by use of the SD margin 

484 legend. 

485 sem Semaphores 

486 The functionality described is optional. The functionality described is also an extension to the 

487 ISO C standard. 

488 Where applicable, functions are marked with the SEM margin legend in the SYNOPSIS section. 

489 Where additional semantics apply to a function, the material is identified by use of the SEM 

490 margin legend. 

491 shm Shared Memory Objects 

492 The functionality described is optional. The functionality described is also an extension to the 

493 ISO C standard. 
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494 Where applicable, functions are marked with the SHM margin legend in the SYNOPSIS section. 

495 Where additional semantics apply to a function, the material is identified by use of the SHM 

496 margin legend. 

497 sio Synchronized Input and Output 

498 The functionality described is optional. The functionality described is also an extension to the 

499 ISO C standard. 

500 Where applicable, functions are marked with the SIO margin legend in the SYNOPSIS section. 

501 Where additional semantics apply to a function, the material is identified by use of the SIO 

502 margin legend. 

503 spi Spin Locks 

504 The functionality described is optional. The functionality described is also an extension to the 

505 ISO C standard. 

506 Where applicable, functions are marked with the SPI margin legend in the SYNOPSIS section. 

507 Where additional semantics apply to a function, the material is identified by use of the SPI 

508 margin legend. 

509 spn Spawn 

510 The functionality described is optional. The functionality described is also an extension to the 

511 ISO C standard. 

512 Where applicable, functions are marked with the SPN margin legend in the SYNOPSIS section. 

513 Where additional semantics apply to a function, the material is identified by use of the SPN 

514 margin legend. 

515 ss Process Sporadic Server 

516 The functionality described is optional. The functionality described is also an extension to the 

517 ISO C standard. 

518 Where applicable, functions are marked with the SS margin legend in the SYNOPSIS section. 

519 Where additional semantics apply to a function, the material is identified by use of the SS 

520 margin legend. 

521 tct Thread CPU-Time Clocks 

522 The functionality described is optional. The functionality described is also an extension to the 

523 ISO C standard. 

524 Where applicable, functions are marked with the TCT margin legend in the SYNOPSIS section. 

525 Where additional semantics apply to a function, the material is identified by use of the TCT 

526 margin legend. 

527 thr Threads 

528 The functionality described is optional. The functionality described is also an extension to the 

529 ISO C standard. 

530 Where applicable, functions are marked with the THR margin legend in the SYNOPSIS section. 

531 Where additional semantics apply to a function, the material is identified by use of the THR 

532 margin legend. 

533 tmo Timeouts 

534 The functionality described is optional. The functionality described is also an extension to the 

535 ISO C standard. 

536 Where applicable, functions are marked with the TMO margin legend in the SYNOPSIS section. 

537 Where additional semantics apply to a function, the material is identified by use of the TMO 

538 margin legend. 
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539 

TMR 

Timers 

540 


The functionality described is optional. 

541 


ISO C standard. 

542 


Where applicable, functions are marked 

543 


Where additional semantics apply to a 

544 


margin legend. 

545 

TPI 

Threads Priority Inheritance 

546 


The functionality described is optional. 

547 


ISO C standard. 

548 


Where applicable, functions are marked 

549 


Where additional semantics apply to a 

550 


margin legend. 

551 

TPP 

Thread Priority Protection 

552 


The functionality described is optional. 

553 


ISO C standard. 

554 


Where applicable, functions are marked 

555 


Where additional semantics apply to a 

556 


margin legend. 

557 

TPS 

Thread Execution Scheduling 

558 


The functionality described is optional. 

559 


ISO C standard. 

560 


Where applicable, functions are marked 

561 


Where additional semantics apply to a 

562 


margin legend. 

563 

TSA 

Thread Stack Address Attribute 

564 


The functionality described is optional. 

565 


ISO C standard. 

566 


Where applicable, functions are marked 

567 


Where additional semantics apply to a 

568 


margin legend. 

569 

TSF 

Thread-Safe Functions 

570 


The functionality described is optional. 

571 


ISO C standard. 

572 


Where applicable, functions are marked 

573 


Where additional semantics apply to a 

574 


margin legend. 

575 

TSH 

Thread Process-Shared Synchronization 

576 


The functionality described is optional. 

577 


ISO C standard. 

578 


Where applicable, functions are marked 

579 


Where additional semantics apply to a 

580 


margin legend. 

581 

TSP 

Thread Sporadic Server 

582 


The functionality described is optional. 

583 


ISO C standard. 
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584 Where applicable, functions are marked with the TSP margin legend in the SYNOPSIS section. 

585 Where additional semantics apply to a function, the material is identified by use of the TSP 

586 margin legend. 

587 tss Thread Stack Address Size 

588 The functionality described is optional. The functionality described is also an extension to the 

589 ISO C standard. 

590 Where applicable, functions are marked with the TSS margin legend in the SYNOPSIS section. 

591 Where additional semantics apply to a function, the material is identified by use of the TSS 

592 margin legend. 

593 tym Typed Memory Objects 

594 The functionality described is optional. The functionality described is also an extension to the 

595 ISO C standard. 

596 Where applicable, functions are marked with the TYM margin legend in the SYNOPSIS section. 

597 Where additional semantics apply to a function, the material is identified by use of the TYM 

598 margin legend. 

599 un Possibly Unsupportable Feature 

600 The functionality described is an XSI extension. It need not be possible to implement the 

601 required functionality (as defined) on all conformant systems and the functionality need not be 

602 present. This may, for example, be the case where the conformant system is hosted and the 

603 underlying system provides the service in an alternative way. 

604 up User Portability Utilities 

605 The functionality described is optional. 

606 Where applicable, utilities are marked with the UP margin legend in the SYNOPSIS section. 

607 Where additional semantics apply to a utility, the material is identified by use of the UP margin 

608 legend. 

609 xsi Extension 

610 The functionality described is an XSI extension. Functionality marked XSI is also an extension to 

611 the ISO C standard. Application writers may confidently make use of an extension on all 

612 systems supporting the X/Open System Interfaces Extension. 

613 If an entire SYNOPSIS section is shaded and marked with one XSI, all the functionality described 

614 in that reference page is an extension. See the System Interface Definitions volume of 

615 IEEE Std. 1003.1-200x, Section 3.436, XSI. 

616 xsr XSI STREAMS 

617 The functionality described is optional. The functionality described is also an extension to the 

618 ISO C standard. 

619 Where applicable, functions are marked with the XSR margin legend in the SYNOPSIS section. 

620 Where additional semantics apply to a function, the material is identified by use of the XSR 

621 margin legend. 
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622 1.10 Format of Entries 


623 The entries in Chapter 3 are based on a common format as follows. The only sections relating to 

624 conformance are the SYNOPSIS, DESCRIPTION, RETURN VALUE, and ERRORS sections. 


625 NAME 

626 This section gives the name or names of the entry and briefly states its purpose. 


627 

628 

629 

630 


SYNOPSIS 

This section summarizes the use of the entry being described. If it is necessary to 
include a header to use this function, the names of such headers are shown, for 
example: 


631 #include <stdio.h> 

632 DESCRIPTION 

633 This section describes the functionality of the function or header. 


634 RETURN VALUE 

635 This section indicates the possible return values, if any. 


636 

637 

638 


If the implementation can detect errors, "successful completion" means that no error 
has been detected during execution of the function. If the implementation does detect 
an error, the error is indicated. 


639 

640 

641 

642 


For functions where no errors are defined, "successful completion" means that if the 
implementation checks for errors, no error has been detected. If the implementation can 
detect errors, and an error is detected, the indicated return value is returned and errno 
may be set. 


643 ERRORS 

644 This section gives the symbolic names of the values returned in errno if an error occurs. 


645 "No errors are defined" means that values and usage of errno, if any, depend on the 

646 implementation. 


647 EXAMPLES 

648 This section is non-normative. 


649 

650 

651 


This section gives examples of usage, where appropriate. In the event of conflict 
between an example and a normative part of this volume of IEEE Std. 1003.1-200x, the 
normative material is to be taken as correct. 


652 APPLICATION USAGE 

653 This section is non-normative. 


654 

655 

656 


This section gives warnings and advice to application writers about the entry. In the 
event of conflict between warnings and advice and a normative part of this volume of 
IEEE Std. 1003.1-200x, the normative material is to be taken as correct. 


657 RATIONALE 

658 This section is non-normative. 


659 

660 
661 


This section contains historical information concerning the contents of this volume of 
IEEE Std. 1003.1-200x and why features were included or discarded by the standard 
developers. 


662 FUTURE DIRECTIONS 

663 This section is non-normative. 
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664 This section provides comments which should be used as a guide to current thinking; 

665 there is not necessarily a commitment to adopt these future directions. 

666 SEE ALSO 

667 This section is non-normative. 

668 This section gives references to related information. 

669 CHANGE HISTORY 

670 This section is non-normative. 

671 This section shows the derivation of the entry and any significant changes that have 

672 been made to it. 
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Chapter 2 

General Information 


674 This chapter covers information that is relevant to all the functions specified in Chapter 3 and 

675 the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 13, Headers: 

676 • Use and Implementation of Functions (see Section 2.1 on page 26) 

677 • Compilation Environment (see Section 2.2 on page 27) 

678 • Error Numbers (see Section 2.3 on page 35) 

679 • Signal Concepts (see Section 2.4 on page 43) 

680 • Standard I/O Streams (see Section 2.5 on page 50) 

681 • STREAMS (see Section 2.6 on page 55) 

682 • XSI Interprocess Communication (IPC) (see Section 2.7 on page 57) 

683 • Realtime (see Section 2.8 on page 59) 

684 • Threads (see Section 2.9 on page 70) 

685 • Sockets (see Section 2.10 on page 81) 

686 • Data Types (see Section 2.11 on page 93) 
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687 2.1 


688 

689 

690 

691 

692 

693 

694 

695 

696 

697 

698 

699 

700 

701 

702 

703 

704 

705 

706 

707 

708 

709 

710 


Use and Implementation of Functions 

Each of the following statements shall apply unless explicitly stated otherwise in the detailed 
descriptions that follow: 

1. If an argument to a function has an invalid value (such as a value outside the domain of 
the function, or a pointer outside the address space of the program, or a null pointer), the 
behavior is undefined. 

2. Any function declared in a header may also be implemented as a macro defined in the 
header, so a library function should not be declared explicitly if its header is included. Any 
macro definition of a function can be suppressed locally by enclosing the name of the 
function in parentheses, because the name is then not followed by the left parenthesis that 
indicates expansion of a macro function name. For the same syntactic reason, it is 
permitted to take the address of a library function even if it is also defined as a macro. The 
use of the C-language #undef construct to remove any such macro definition shall also 
ensure that an actual function is referred to. 

3. Any invocation of a library function that is implemented as a macro shall expand to code 
that evaluates each of its arguments exactly once, fully protected by parentheses where 
necessary, so it is generally safe to use arbitrary expressions as arguments. Likewise, those 
function-like macros described in the following sections may be invoked in an expression 
anywhere a function with a compatible return type could be called. 

4. Provided that a library function can be declared without reference to any type defined in a 
header, it is also permissible to declare the function, either explicitly or implicitly, and use 
it without including its associated header. 

5. If a function that accepts a variable number of arguments is not declared (explicitly or by 
including its associated header), the behavior is undefined. 
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7ii 2.2 The Compilation Environment 


712 2.2.1 POSIX.l Symbols 


713 

714 

715 

716 

717 

718 


Certain symbols in this volume of IEEE Std. 1003.1-200x are defined in headers (see the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 13, Headers). Some of those 
headers could also define other symbols than those defined by this volume of 
IEEE Std. 1003.1-200x, potentially conflicting with symbols used by the application. Also, this 
volume of IEEE Std. 1003.1-200x defines symbols that are not permitted by other standards to 
appear in those headers without some control on the visibility of those symbols. 


719 Symbols called feature test macros are used to control the visibility of symbols that might be 

720 included in a header. Implementations, future versions of this volume of IEEE Std. 1003.1-200x, 

721 and other standards may define additional feature test macros. 


722 

723 

724 

725 

726 


In the compilation of an application that #defines a feature test macro specified by 
IEEE Std. 1003.1-200x, no header defined by IEEE Std. 1003.1-200x shall be included prior to the 
definition of the feature test macro. This restriction also applies to any implementation- 
provided header in which these feature test macros are used. If the definition of the macro does 
not precede the #include, the result is undefined. 


727 


Feature test macros shall begin with the underscore character 


728 2.2.1.1 The _POSIX_C_SOURCE Feature Test Macro 

729 A POSIX-conforming application should ensure that the feature test macro _POSIX_C_SOURCE 

730 is defined before inclusion of any header. 

731 When an application includes a header described by this volume of IEEE Std. 1003.1-200x, and 

732 when this feature test macro is defined to have at least the value 200xMML: 


733 1. All symbols required by this volume of IEEE Std. 1003.1-200x to appear when the header is 

734 included shall be made visible. 


735 

736 

737 


2. Symbols that are explicitly permitted, but not required, by this volume of 
IEEE Std. 1003.1-200x to appear in that header (including those in reserved name spaces) 
may be made visible. 


738 

739 

740 

741 


3. Additional symbols not required or explicitly permitted by this volume of 
IEEE Std. 1003.1-200x to be in that header shall not be made visible, except when enabled 
by another feature test macro or by having defined _POSIX_C_SOURCE with a value 
larger than 200xxxL. 


742 

743 

744 

745 


Identifiers in this volume of IEEE Std. 1003.1-200x may only be undefined using the #undef 
directive as described in Section 2.1 on page 26 or Section 2.2.2 on page 28. These #undef 
directives shall follow all #include directives of any header in this volume of 
IEEE Std. 1003.1-200x. 


746 Rationale 

747 Since _POSIX_SOURCE specified by the POSIX. 1-1990 standard did not have a value associated 

748 with it, the _POSIX_C_SOURCE macro replaces it, allowing an application to inform the system 

749 of the revision of the standard to which it conforms. This symbol will allow implementations to 

750 support various revisions of IEEE Std. 1003.1-200x simultaneously. For instance, when either 

751 _POSIX_SOURCE is defined or _POSIX_C_SOURCE is defined as 1, the system should make 

752 visible the same name space as permitted and required by the POSIX.1-1990 standard. When 

753 _POSIX_C_SOURCE is defined, the state of _POSIX_SOURCE is completely irrelevant. 
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754 It is expected that C bindings to future POSIX standards will define new values for 

755 _POSIX_C_SOURCE, with each new value reserving the name space for that new standard, plus 

756 all earlier POSIX standards. Using a single feature test macro for all standards rather than a 

757 separate macro for each standard furthers the goal of eventually combining all of the C bindings 

758 into one standard. 

759 It is further intended that these feature test macros apply only to the headers specified by 

760 IEEE Std. 1003.1-200x. Implementations are expressly permitted to make visible symbols not 

761 specified by IEEE Std. 1003.1-200x, within both IEEE Std. 1003.1-200x and other headers, under 

762 the control of feature test macros that are not defined by IEEE Std. 1003.1-200x. 


763 2.2.1.2 The _XOPEN_SOURCE Feature Test Macro 

764 xsi An XSI-conforming application should ensure that the feature test macro _XOPEN_SOURCE is 

765 defined with the value 600 before inclusion of any header. This is needed to enable the 

766 functionality described in Section 2.2.1.1 on page 27 and in addition to enable the X/Open 

767 System Interfaces Extension. 

768 Since this volume of IEEE Std. 1003.1-200x is aligned with the ISO C standard, and since all 

769 functionality enabled by _POSIX_C_SOURCE set greater than zero and less than or equal to 

770 200xxxL should be enabled by _XOPEN_SOURCE set equal to 600, there should be no need to 

771 define either _POSIX_SOURCE or _POSIX_C_SOURCE if _XOPEN_SOURCE is so defined. 

772 Therefore, if _XOPEN_SOURCE is set equal to 600 and _POSIX_SOURCE is defined, or 

773 _POSIX_C_SOURCE is set greater than zero and less than or equal to 200xxxL, the behavior is 

774 the same as if only _XOPEN_SOURCE is defined and set equal to 600. However, should 

775 _POSIX_C_SOURCE be set to a value greater than 200xxxL, the behavior is undefined. 


776 2.2.2 The Name Space 


777 

778 

779 XSI 

780 

781 

782 

783 

784 


All identifiers in this volume of IEEE Std. 1003.1-200x, except environ , are defined in at least one 
of the headers, as shown in the System Interface Definitions volume of IEEE Std. 1003.1-200x, 
Chapter 13, Headers. When _XOPEN_SOURCE or_POSIX_C_SOURCE is defined, each header 
defines or declares some identifiers, potentially conflicting with identifiers used by the 
application. The set of identifiers visible to the application consists of precisely those identifiers 
from the header pages of the included headers, as well as additional identifiers reserved for the 
implementation. In addition, some headers may make visible identifiers from other headers as 
indicated on the relevant header pages. 


785 

786 

787 

788 


Implementations may also add members to a structure or union without controlling the 
visibility of those members with a feature test macro, as long as a user-defined macro with the 
same name cannot interfere with the correct interpretation of the program. The identifiers 
reserved for use by the implementation are described below: 


789 

790 


1. Each identifier with external linkage described in the header section is reserved for use as 
an identifier with external linkage if the header is included. 


791 

792 


2. Each macro name described in the header section is reserved for any use if the header is 
included. 


793 

794 


3. Each identifier with file scope described in the header section is reserved for use as an 
identifier with file scope in the same name space if the header is included. 


795 

796 

797 

798 

799 


The prefixes posix_, POSIX_, and _POSIX_ are reserved for use by IEEE Std. 1003.1-200x and 
other POSIX standards. Implementations may add symbols to the headers shown in the 
following table, provided the identifiers for those symbols begin with the corresponding 
reserved prefixes in the following table, and do not use the reserved prefixes posix_, POSIX_, or 
_POSIX_. 
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800 


801 

802 


Header 

Prefix 

Suffix 

Complete 

Name 

803 

AIO 

<aio.h> 

aio_, lio_, AIO_, LIO_ 



804 


<arpa/inet.h> 

in_, inet_ 



805 


<dirent.h> 

d_ 



806 


<errno.h> 

E 



807 


<fcntl.h> 

1_ 



808 


<glob.h> 

gL 



809 


<grp.h> 

g r - 



810 


<limits.h> 


_MAX, _MIN 


811 


<locale.h> 

LC_[A-Z] 



812 

MSG 

<mqueue.h> 

mq_, MQ_ 



813 

XSI 

<ndbm.h> 

dbm_ 



814 


<netdb.h> 

h_, n_, p_, s_ 



815 


<net/if.h> 

if_ 



816 


<netinet/in.h> 

in_, ip_, s_, sin_ 



817 

XSI 

<poll.h> 

pd_, ph_, ps_ 



818 


<pthread.h> 

pthread_, PTHREAD_ 



819 


<pwd.h> 

pw_ 



820 


<regex.h> 

re_, rm_ 



821 

PS 

<sched.h> 

sched_, SCHED_ 



822 

SEM 

<semaphore.h> 

sem_, SEM_ 



823 


<signal.h> 

sa^ uc_, SIG[A-Z], SIG_[A-Z] 



824 

XSI 


ss_, sv_ 



825 

RTS 


si_, SI_, sigev_, SIGEV_, sival_ 



826 

XSI 

<stropts.h> 

bi_, ic_, 1_, sl_, str_ 



827 

XSI 

<sys/ipc.h> 

ipc_ 


key, pad, seq 

828 

MF 

<sys/mman.h> 

shm_, MAP_, MCL_, MS_, PROT_ 



829 

XSI 

<sys/msg.h> 

msg 


msg 

830 

XSI 

<sys/resource.h> 

rlim_, ru_ 



831 

XSI 

<sys/sem.h> 

sem 


sem 

832 

XSI 

<sys/shm.h> 

shm 



833 


<sys/socket.h> 

_ss, sa_, if_, ifc_, ifru_, infu_, ifra_. 



834 



msg_, cmsg_, 1_ 



835 


<sys/stat.h> 

st_ 



836 

XSI 

<sys/statvfs.h> 

f_ 



837 


<sys/time.h> 

fds_, it_, tv_, FD_ 



838 


<sys/times.h> 

tms_ 



839 

XSI 

<sys/uio.h> 

iov_ 



840 


<sys/un.h> 

sun_ 



841 


<sys/utsname.h> 

uts_ 



842 

XSI 

<sys/wait.h> 

si_, W[A-Z], P_ 



843 


<termios.h> 

c_ 
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845 

846 


Header 

Prefix 

Suffix 

Complete 1 
Name 

847 


<time.h> 

tm_ 



848 

TMR 


clock_, timer_, it_, tv_. 



849 

TMR 


CLOCK., TIMER. 



850 

XSI 

<ucontext.h> 

uc_, ss_ 



851 

XSI 

<ulimit.h> 

UL_ 



852 


<utime.h> 

utim. 



853 

XSI 

<utmpx.h> 

ut_ 

_LV L, .TIME, .PROCESS 


854 


<wordexp.h> 

we_ 



855 


ANY header 

POSIX., .POSIX., posix. 

_t 

1 


856 Note: The notation [A-Z] indicates any uppercase letter in the portable character set. The I 

857 notation [a-z] indicates any lowercase letter in the portable character set. Commas I 

858 and spaces in the lists of prefixes and complete names in the above table are not part I 

859 of any prefix or complete name. I 

860 Rationale I 

861 Since both implementations and future revisions of IEEE Std. 1003.1-200x and other POSIX I 

862 standards may use symbols in the reserved spaces described in these tables, there is a potential I 

863 for name space clashes. To avoid future name space clashes when adding symbols, I 

864 implementations should not use the posix_, POSIX_, or _POSIX_ prefixes. I 

865 If any header in the following table is included, macros with the prefixes shown may be defined. I 

866 After the last inclusion of a given header, an application may use identifiers with the 

867 corresponding prefixes for its own purpose, provided their use is preceded by an #undef of the 

868 corresponding macro. 
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869 


870 


Header 

Prefix 

871 

XSI 

<dflcn.h> 

RTLD_ 

872 


<fcntl.h> 

F_, 0_, S_ 

873 

XSI 

<fmtmsg.h> 

MM_ 

874 


<fnmatch.h> 

FNM_ 

875 

XSI 

<ftw.h> 

FTW 

876 


<glob.h> 

GLOB_ 

877 

XSI 

<ndbm.h> 

DBM_ 

878 


<net/if.h> 

IF_ 

879 


<netinet/in.h> 

IMPLINK_, IN_, INADDR_, IP_, IPPORT_, IPPROTO_, SOCK_ 

880 


<netinet/tcp.h> 

TCP_ 

881 

XSI 

<nl_types.h> 

NL_ 

882 

XSI 

<poll.h> 

POLL 

883 


<regex.h> 

REG_ 

884 


<signal.h> 

SA_, SIG_[0-9a-z_], 

885 

XSI 


BUS , CLD , FPE , ILL ,POLL ,SEGV ,SI ,SS ,SV , TRAP 

886 

XSI 

<stropts.h> 

FLUSH[A-Z], I_, M_, MUXID_R[A-Z], S_, SND[A-Z], STR 

887 

XSI 

<syslog.h> 

LOG_ 

888 

XSI 

<sys/ipc.h> 

IPC_ 

889 

XSI 

<sys/mman.h> 

PROT_, MAP_, MS_ 

890 

XSI 

<sys/msg.h> 

MSG [A-Z] 

891 

XSI 

<sys/resource.h> 

PRIO_, RLIM_, RLIMIT_, RUSAGE_ 

892 

XSI 

<sys/sem.h> 

SEM_ 

893 

XSI 

<sys/shm.h> 

SHM[A-Z], SHM_[A-Z] 

894 

XSI 

<sys/socket.h> 

AF^ CMSG_, MSG_, PF_, SCM_, SHUT_, SO 

895 


<sys/stat.h> 

S_ 

896 

XSI 

<sys/statvfs.h> 

ST_ 

897 

XSI 

<sys/time.h> 

FD_, ITIMER_ 

898 

XSI 

<sys/uio.h> 

IOV_ 

899 

XSI 

<sys/wait.h> 

BUS_, CLD_, FPE_, ILL_, POLL_, SEGV_, SI_, TRAP_ 

900 


<termios.h> 

V, I, O, TC, B[0-9] 

901 


<wordexp.h> 

WRDE_ 


902 

903 

904 


Note: The notation [0-9] indicates any digit. The notation [A-Z] indicates any uppercase 

letter in the portable character set. The notation [0-9a-z_] indicates any digit, any 
lowercase letter in the portable character set, or underscore. 
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905 The following identifiers are reserved regardless of the inclusion of headers: 

906 1. All identifiers that begin with an underscore and either an uppercase letter or another 

907 underscore are always reserved for any use by the implementation. 

908 2. All identifiers that begin with an underscore are always reserved for use as identifiers with 

909 file scope in both the ordinary identifier and tag name spaces. 

910 3. All identifiers in the table below are reserved for use as identifiers with external linkage. 

911 Some of these identifiers do not appear in this volume of IEEE Std. 1003.1-200x, but are 

912 reserved for future use by the ISO C standard. 

913 


914 

abort 

cosl 

fputwc 

log 

raise 

tanhf 

915 

abs 

ctime 

fputws 

loglO 

rand 

tanhl 

916 

acos 

difftime 

tread 

loglOf 

realloc 

tanl 

917 

acosf 

div 

free 

loglOl 

remove 

time 

918 

acosl 

errno 

freopen 

logf 

rename 

tmpfile 

919 

asctime 

exit 

frexp 

logl 

rewind 

tmpnam 

920 

asin 

exp 

frexpf 

longjmp 

scant 

to[a-z]* 

921 

asinf 

expf 

frexpl 

malloc 

setbuf 

ungetc 

922 

asinl 

expl 

fscanf 

mblen 

setjmp 

ungetwc 

923 

atan 

tabs 

fseek 

mbrlen 

setlocale 

va_end 

924 

atan2 

fabsf 

fsetpos 

mbrtowc 

setvbuf 

vfprintf 

925 

atan2f 

fabsl 

ftell 

mbsinit 

signal 

vfwprintf 

926 

atan21 

fclose 

fwide 

mbsrtowcs 

sin 

vprintf 

927 

atanf 

feof 

fwprintf 

mbstowcs 

sinf 

vsprintf 

928 

atanl 

terror 

fwrite 

mbtowc 

sinh 

vswprintf 

929 

atexit 

fflush 

fwscanf 

mem[a-z]* 

sinhf 

vwprintf 

930 

atof 

fgetc 

getc 

mktime 

sinhl 

wcrtomb 

931 

atoi 

fgetpos 

getchar 

modf 

sinl 

wcs[a-z]* 

932 

atol 

fgets 

getenv 

modff 

sprintf 

wctob 

933 

bsearch 

fgetwc 

gets 

modfl 

sqrt 

wctomb 

934 

calloc 

fgetws 

getwc 

perror 

sqrtf 

wctrans 

935 

ceil 

floor 

getwchar 

pow 

sqrtl 

wctype 

936 

ceilf 

floorf 

gmtime 

powf 

srand 

wcwidth 

937 

ceill 

floorl 

is[a-z]* 

powl 

sscanf 

wmem[a-z]* 

938 

clearerr 

fmod 

labs 

printf 

str[a-z]* 

wprintf 

939 

clock 

fmodf 

ldexp 

putc 

swprintf 

wscanf 

940 

cos 

fmodl 

ldexpf 

putchar 

swscanf 


941 

cost 

fopen 

ldexpl 

puts 

system 


942 

cosh 

fprintf 

ldiv 

putwc 

tan 


943 

coshf 

fputc 

localeconv 

putwchar 

tanf 


944 

coshl 

fputs 

localtime 

qsort 

tanh 



945 Note: The notation [a-z] indicates any lowercase letter in the portable character set. 

946 The notation ' *' indicates any combination of digits, letters in the portable 

947 character set, and underscore. 
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948 Notes to Reviewers 

949 This section with side shading will not appear in the final copy. - Ed. 

950 The following table should be made complete by including everything not in the previous 

951 table. 

952 4. The following identifiers are also reserved for use as identifiers with external linkage: 


953 Table 2-1 XSI Identifiers 

954 


955 

a641 

endutxent 

getpriority 

makecontext 

remainder 

sigstack 

956 


acosh 

expml 

getpwent 

mknod 

remque 

srandom 

957 


asinh 

fattach 

getrlimit 

mkstemp 

rindex 

statvfs 

958 


atanh 

fchdir 

getrusage 

mktemp 

rint 

strcasecmp 

959 


basename 

fchmod 

getsid 

mmap 

sbrk 

strdup 

960 


bcmp 

fchown 

getsubopt 

mprotect 

scalb 

strncasecmp 

961 


bcopy 

fcvt 

gettimeofday mrand48 

select 

swapcontext 

962 


brk 

fdetach 

getutxent 

msync 

setcontext 

symlink 

963 


bsd_signal 

ffs 

getutxid 

munmap 

setgrent 

sync 

964 


bzero 

fmtmsg 

getutxline 

nextafter 

setitimer 

syslog 

965 


cbrt 

fstatvfs 

getwd 

nftw 

_setjmp 

tcgetsid 

966 


closelog 

ftime 

grantpt 

nice 

setlogmask 

truncate 

967 


dbm_clearerr 

ftok 

ilogb 

openlog 

setpgrp 

ttyslot 

968 


dbm_close 

ftruncate 

index 

poll 

setpriority 

ualarm 

969 


dbm_delete 

gcvt 

initstate 

ptsname 

setpwent 

unlockpt 

970 


dbm_error 

getcontext 

insque 

putmsg 

setreuid 

usleep 

971 


dbm_fetch 

getdate 

ioctl 

putpmsg 

setrlimit 

utimes 

972 


dbm_firstkey 

getdtablesize 

isastream 

pututxline 

setstate 

valloc 

973 


dbm_nextkey 

getgrent 

killpg 

random 

setutxent 

vfork 

974 


dbm_open 

getgrgid 

164a 

readlink 

sigaltstack 

wait3 

975 


dbm_store 

gethostid 

lchown 

readv 

sighold 

waitid 

976 


dirname 

getitimer 

lockf 

realpath 

sigignore 

writev 

977 


ecvt 

getmsg 

loglp 

re_comp 

siginterrupt 


978 


endgrent 

getpagesize 

logb 

re_exec 

sigpause 


979 


endpwent 

getpgid 

Jongjmp 

regcmp 

sigrelse 


980 


endservent 

getpmsg 

lstat 

regex 

sigset 



981 Table 2-2 Sockets Identifiers 

982 


983 

accept 

i f_ f r e b n a m e i n d e x recvftom 

shutdown 

984 

bind 

if_indextoname 

recvnhsg 

sockelt 

985 

connect 

if_natneindex 

send 1 

sockeltpair 

986 

getpeemame 

ifnatnetoindex 

sendilnsg 

1 

987 

getsockname 

listen! 

sendtb 

1 

988 

getsockopt 

recv 1 

setsoikopt 

1 
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989 

990 

991 

992 

993 

994 

995 

996 

997 

998 

999 


Table 2-3 IP Address Resolution Identifiers 


endhostent 

geti jano debya ddr 

getslervbyname 

inetLnetof 

endnetent 

getijanodebyname 

getslervbyport 

inetLnetwork 

endprotoent 

getriameinfo 

getslervent 

inetLntoa 

endservent 

getrletbyaddr 

h_eirno 

ntohl 

getaddrinfo 

getrietbyname 

htohl 

ntohs 

gethostbyaddr 

getrietent 

htohs 

sethlostent 

gethostbyname 

getjlro toby name 

inetLaddr 

setnletent 

gethostent 

ge t ji ro tob y n n m be r 

inetjjnaof 

setplrotoent 

gethostname 

getjlro toe nt 

inetLmakeaddr 

setsbrvent 


1000 All the identifiers defined in this volume of IEEE Std. 1003.1-200x that have external linkage are I 

1001 always reserved for use as identifiers with external linkage. 

1002 No other identifiers are reserved. 

1003 Applications shall not declare or define identifiers with the same name as an identifier reserved I 

1004 in the same context. Since macro names are replaced whenever found, independent of scope and 

1005 name space, macro names matching any of the reserved identifier names shall not be defined by I 

1006 an application if any associated header is included. I 

1007 man Except that the effect of each inclusion of <assert.h> depends on the definition of NDEBUG, 

1008 headers may be included in any order, and each may be included more than once in a given 

1009 scope, with no difference in effect from that of being included only once. 

1010 If used, the application shall ensure that a header is included outside of any external declaration I 

1011 or definition, and it shall be first included before the first reference to any type or macro it I 

1012 defines, or to any function or object it declares. However, if an identifier is declared or defined in I 

1013 more than one header, the second and subsequent associated headers may be included after the I 

1014 initial reference to the identifier. Prior to the inclusion of a header, the application shall not I 

1015 define any macros with names lexically identical to symbols defined by that header. I 
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1016 2.3 Error Numbers 

1017 Most functions can provide an error number. The means by which each function provides its 

1018 error numbers is specified in its description. 

1019 Some functions provide the error number in a variable accessed through the symbol errno. The 

1020 symbol errno, defined by including the header <errno.h>, is a macro that expands to a 

1021 modifiable lvalue of type int. 

1022 The value of errno should only be examined when it is indicated to be valid by a function's return 

1023 value. No function in this volume of IEEE Std. 1003.1-200x shall set errno to zero to indicate an 

1024 error. For each thread of a process, the value of errno shall not be affected by function calls or 

1025 assignments to errno by other threads. 

1026 Some functions return an error number directly as the function value. These functions return a 

1027 value of zero to indicate success. 

1028 If more than one error occurs in processing a function call, any one of the possible errors may be 

1029 returned, as the order of detection is undefined. 

1030 Implementations may support additional errors not included in this list, may generate errors 

1031 included in this list under circumstances other than those described here, or may contain 

1032 extensions or limitations that shall prevent some errors from occurring. The ERRORS section on 

1033 each page specifies whether an error shall be returned, or whether it may be returned. 

1034 Implementations shall not generate a different error number from the ones described here for 

1035 error conditions described in this volume of IEEE Std. 1003.1-200x, but may generate additional 

1036 errors unless explicitly disallowed for a particular function. 

1037 Each implementation shall document, in the conformance document, situations in which each of I 

1038 the optional conditions defined in IEEE Std. 1003.1-200x are detected. The conformance I 

1039 document may also contain statements that one or more of the optional error conditions are not I 

1040 detected. I 

1041 Rationale I 

1042 It was the consensus of the standard developers that to allow the conformance document to I 

1043 state that an error occurs and under what conditions, but to disallow a statement that it never I 

1044 occurs, does not make sense. It could be implied by the current wording that this is allowed, but I 

1045 to reduce the possibility of future interpretation requests, it is better to make an explicit I 

1046 statement. I 

1047 For functions under the _POSIX_THREADS option for which [EINTR] is not listed as a possible I 

1048 error condition in this volume of IEEE Std. 1003.1-200x, an implementation shall not return an 

1049 error code of [EINTR]. 

1050 The following symbolic names identify the possible error numbers, in the context of the 

1051 functions specifically defined in this volume of IEEE Std. 1003.1-200x; these general descriptions 

1052 are more precisely defined in the ERRORS sections of the functions that return them. Only these 

1053 symbolic names should be used in programs, since the actual value of the error number is 

1054 man unspecified. All values listed in this section shall be unique except as noted below. The values 

1055 for all these names shall be found in the header <errno.h> defined in the System Interface 

1056 Definitions volume of IEEE Std. 1003.1-200x. The actual values are unspecified by this volume of 

1057 IEEE Std. 1003.1-200x. 

1058 [E2BIG] 

1059 Argument list too long. The sum of the number of bytes used by the new process image's 

1060 argument list and environment list is greater than the system-imposed limit of [ARG_MAX[ 
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1061 bytes. 

1062 or: 

1063 Lack of space in an output buffer. 

1064 or: 

1065 Argument is greater than the system-imposed maximum. 

1066 [EACCES] 

1067 Permission denied. An attempt was made to access a file in a way forbidden by its file 

1068 access permissions. 

1069 man [EADDRINUSE] 

1070 Address in use. The specified address is in use. 

1071 man [EADDRNOTAVAIL] 

1072 Address not available. The specified address is not available from the local system. 

1073 man [EAFNOSUPPORT] 

1074 Address family not supported. The implementation does not support the specified address 

1075 family, or the specified address is not a valid address for the address family of the specified 

1076 socket. 

1077 [EAGAIN] 

1078 Resource temporarily unavailable. This is a temporary condition and later calls to the same 

1079 routine may complete normally. 

1080 man [EALREADY] 

1081 Connection already in progress. A connection request is already in progress for the specified 

1082 socket. 


1083 [EBADF] 

1084 Bad file descriptor. A file descriptor argument is out of range, refers to no open file, or a 

1085 read (write) request is made to a file that is only open for writing (reading). 

1086 [EBADMSG] 

1087 xsi Bad message. During a read (), getmsg( ), or ioctl () I_RECVFD request to a STREAMS device, 

1088 a message arrived at the head of the STREAM that is inappropriate for the function 

1089 receiving the message. 

1090 read () Message waiting to be read on a STREAM is not a data message. 

1091 getmsg() A file descriptor was received instead of a control message. 

1092 ioctl () Control or data information was received instead of a file descriptor when 

1093 I_RECVFD was specified. 

1094 or: 


1095 Bad Message. The implementation has detected a corrupted message. 

1096 [EBUSY] 

1097 Resource busy. An attempt was made to make use of a system resource that is not currently 

1098 available, as it is being used by another process in a manner that would have conflicted with 

1099 the request being made by this process. 

1100 [ECANCELED] 

1101 Operation canceled. The associated asynchronous operation was canceled before 

1102 completion. 
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1103 

1104 

1105 


[ECHILD] 

No child process. A wait () or waitpid () function was executed by a process that had no 
existing or unwaited-for child process. 


1106 man [ECONNABORTED] 

1107 Connection aborted. The connection has been aborted. 


1108 MAN 

1109 

1110 
1111 


[ECONNREFUSED] 

Connection refused. An attempt to connect to a socket was refused because there was no 
process listening or because the queue of connection requests was full and the underlying 
protocol does not support retransmissions. 


1112 man [ECONNRESET] 

1113 Connection reset. The connection was forcibly closed by the peer. 


1114 [EDEADLK] 

1115 Resource deadlock would occur. An attempt was made to lock a system resource that 

1116 would have resulted in a deadlock situation. 


1117 man [EDESTADDRREQ] 

1118 Destination address required. No bind address was established. 

1119 [EDOM] 

1120 Domain error. An input argument is outside the defined domain of the mathematical 

1121 function (defined in the ISO C standard). 


1122 MAN [EDQUOT] 

1123 Reserved. 


1124 

1125 

1126 


[EEXIST] 

File exists. An existing file was mentioned in an inappropriate context; for example, as a 
new link name in the link () function. 


1127 

1128 

1129 

1130 

1131 


[EFAULT] 

Bad address. The system detected an invalid address in attempting to use an argument of a 
call. The reliable detection of this error cannot be guaranteed, and when not detected may 
result in the generation of a signal, indicating an address violation, which is sent to the 
process. 


1132 man [EFBIG] 

1133 File too large. The size of a file would exceed the maximum file size of an implementation or 

1134 offset maximum established in the corresponding file description. 

1135 man [EHOSTUNREACH] 

1136 Host is unreachable. The destination host cannot be reached (probably because the host is 

1137 down or a remote router cannot reach it). 


1138 MAN [EIDRM] 

1139 Identifier removed. Returned during XSI interprocess communication if an identifier has 

1140 been removed from the system. 


1141 MAN 

1142 

1143 

1144 


[EINPROGRESS] 

Operation in progress. This code is used to indicate that an asynchronous operation has not 
yet completed. 

or: 


1145 0_NONBLOCK is set for the socket file descriptor and the connection cannot be I 

1146 immediately established. 
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1147 MAN 


1150 MAN 


1155 MAN 


1162 MAN 


1166 MAN 


1187 MAN 


[EILSEQ] 

Illegal byte sequence. A wide-character code has been detected that does not correspond to 
a valid character, or a byte sequence does not form a valid wide-character code. 

[EINTR] 

Interrupted function call. An asynchronous signal was caught by the process during the 
execution of an interruptible function. If the signal handler performs a normal return, the 
interrupted function call may return this condition (see the System Interface Definitions 
volume of IEEE Std. 1003.1-200x, <signal.h>). 

[EINVAL] 

Invalid argument. Some invalid argument was supplied; for example, specifying an 
undefined signal in a signal () function or a kill () function. 

[EIO] 

Input/output error. Some physical input or output error has occurred. This error may be 
reported on a subsequent operation on the same file descriptor. Any other error-causing 
operation on the same file descriptor may cause the [EIO] error indication to be lost. 

[EISCONN] 

Socket is connected. The specified socket is already connected. 

[EISDIR] 

Is a directory. An attempt was made to open a directory with write mode specified. 

[ELOOP] 

Symbolic link loop. A loop exists in symbolic links encountered during path name 
resolution. This error may also be returned if more than ]SYMLOOP_MAX} symbolic links 
are encountered during path name resolution. 

Rationale 

In specifying conditions under which implementations would generate this error, the 
following goals were considered: 

1. To ensure that actual loops are detected, including loops that result from symbolic 
links across distributed file systems. 

2. To ensure that during path name resolution an application can rely on the ability to 
follow at least |SYMLOOP_MAX] symbolic links in the absence of a loop. 

3. To allow implementations to provide the capability of traversing more than 
]SYMLOOP_MAX} symbolic links in the absence of a loop. 

4. To allow implementations to detect loops and generate the error prior to encountering 
|SYMLOOP_MAX] symbolic links. 

[EMFILE] 

Too many open files. An attempt was made to open more than the maximum number of 
]OPEN_MAX] file descriptors allowed in this process. 

[EMLINK] 

Too many links. An attempt was made to have the link count of a single file exceed 
|LINK_MAX}. 

[EMSGSIZE] 

Message too large. A message sent on a transport provider was larger than an internal 
message buffer or some other network limit. 
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1190 or: Inappropriate message buffer length. 

1191 man [EMULTIHOP] 

1192 Reserved. 


1193 

1194 

1195 

1196 

1197 

1198 


[ENAMETOOLONG] 

File name too long. The length of a path name exceeds |PATH_MAX}, or a path name 
component is longer than |NAME_MAX} and _POSIX_NO_TRUNC was in effect for that 
file. This error may also occur when path name substitution, as a result of encountering a 
symbolic link during path name resolution, results in a path name string the size of which 
exceeds {PATH_MAX}. 


1199 


Rationale 


1200 

1201 

1202 

1203 


When a symbolic link is encountered during path name resolution, the contents of that 
symbolic link are used to create a new path name. The standard developers intended to 
allow, but not require, that implementations enforce the restriction of |PATH_MAX} on the 
result of this path name substitution. 


1204 man [ENETDOWN] 

1205 Network is down. The local function used to reach the destination is down. 


1206 [ENETRESET] 

1207 The connection was aborted by the network. 


1208 man [ENETUNREACH] 

1209 Network unreachable. No route to the network is present. 


1210 

1211 

1212 

1213 


[ENFILE] 

Too many files open in system. Too many files are currently open in the system. The system 
has reached its predefined limit for simultaneously open files and temporarily cannot accept 
requests to open another one. 


1214 MAN 

1215 

1216 

1217 XSI 

1218 No message available. No message is available on the STREAM head read queue. 


[ENOBUFS] 

No buffer space available. Insufficient buffer resources were available in the system to 
perform the socket operation. 

[ENODATA] 


1219 

1220 
1221 


[ENODEV] 

No such device. An attempt was made to apply an inappropriate function to a device; for 
example, trying to read a write-only device such as a printer. 


1222 

1223 

1224 


[ENOENT] 

No such file or directory. A component of a specified path name does not exist, or the path 
name is an empty string. 


1225 

1226 

1227 

1228 


[ENOEXEC] 

Executable file format error. A request is made to execute a file that, although it has the 
appropriate permissions, is not in the format required by the implementation for executable 
files. 


1229 

1230 

1231 


[ENOLCK] 

No locks available. A system-imposed limit on the number of simultaneous file and record 
locks has been reached and no more are currently available. 


1232 MAN [ENOLINK] 

1233 Reserved. 
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1234 

1235 

1236 

1237 MAN 

1238 

1239 

1240 MAN 

1241 Protocol not available. The protocol option specified to setsockopt( ) is not supported by the 

1242 implementation. 

1243 [ENOSPC] 

1244 No space left on a device. During the write ( ) function on a regular file or when extending a 

1245 directory, there is no free space left on the device. 

1246 XSI 

1247 

1248 

1249 

1250 XSI 

1251 Not a STREAM. A STREAM function was attempted on a file descriptor that was not 

1252 associated with a STREAMS device. 

1253 [ENOSYS] 

1254 Function not implemented. An attempt was made to use a function that is not available in 

1255 this implementation. 

1256 man [ENOTCONN] 

1257 Socket not connected. The socket is not connected. 


[ENOSR] 

No STREAM resources. Insufficient STREAMS memory resources are available to perform a 
STREAMS-related function. This is a temporary condition; it may be recovered from if other 
processes release resources. 

[ENOSTR] 


[ENOMEM] 

Not enough space. The new process image requires more memory than is allowed by the 
hardware or system-imposed memory management constraints. 

[ENOMSG] 

No message of the desired type. The message queue does not contain a message of the 
required type during XSI interprocess communication. 

[ENOPROTOOPT] 


1258 [ENOTDIR] 

1259 Not a directory. A component of the specified path name exists, but it is not a directory, 

1260 when a directory was expected. 

1261 [ENOTEMPTY] 

1262 Directory not empty. A directory other than an empty directory was supplied when an I 

1263 empty directory was expected. I 

1264 man [ENOTSOCK] 

1265 Not a socket. The file descriptor does not refer to a socket. 

1266 [ENOTSUP] 

1267 Not supported. The implementation does not support this feature of the Realtime Option 

1268 Group. 

1269 [ENOTTY] 

1270 Inappropriate I/O control operation. A control function has been attempted for a file or 

1271 special file for which the operation is inappropriate. 

1272 [ENXIO] 

1273 No such device or address. Input or output on a special file refers to a device that does not 

1274 exist, or makes a request beyond the capabilities of the device. It may also occur when, for 

1275 example, a tape drive is not on-line. 

1276 man [EOPNOTSUPP] 

1277 Operation not supported on socket. The type of socket (address family or protocol) does not 

1278 support the requested operation. 
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1279 MAN [EOVERFLOW] 

1280 Value too large to be stored in data type. The user ID or group ID of an IPC or file system 

1281 object was too large to be stored into the appropriate member of the caller-provided 

1282 structure. This error shall only occur on implementations that support a larger range of user 

1283 ID or group ID values than the declared structure member can support. This usually occurs 

1284 because the IPC or file system object resides on a remote machine with a larger value of the 

1285 type uid_t, off_t, or gid_t than the local system. 

1286 [EPERM] 

1287 Operation not permitted. An attempt was made to perform an operation limited to 

1288 processes with appropriate privileges or to the owner of a file or other resource. 

1289 [EPIPE] 

1290 man Broken pipe. A write was attempted on a socket, pipe, or FIFO for which there is no process 

1291 to read the data. 

1292 MAN 

1293 

1294 

1295 MAN 

1296 

1297 

1298 MAN 

1299 Socket type not supported. The socket type is not supported by the protocol. 

1300 [ERANGE] 

1301 Result too large or too small. The result of the function is too large (overflow) or too small 

1302 (underflow) to be represented in the available space (defined in the ISO C standard). 

1303 [EROFS] 

1304 Read-only file system. An attempt was made to modify a file or directory on a file system 

1305 that is read-only. 

1306 [ESPIPE] 

1307 Invalid seek. An attempt was made to access the file offset associated with a pipe or FIFO. 

1308 [ESRCH] 

1309 No such process. No process can be found corresponding to that specified by the given 

1310 process ID. 

1311 MAN 

1312 

1313 XSI 

1314 

1315 

1316 

1317 

1318 MAN 

1319 

1320 

1321 

1322 

1323 


[ESTALE] 

Reserved. 

[ETIME] 

STREAM ioctl () timeout. The timer set for a STREAMS ioctl () call has expired. The cause of 
this error is device-specific and could indicate either a hardware or software failure, or a 
timeout value that is too short for the specific operation. The status of the ioctl () operation 
is indeterminate. 

[ETIMEDOUT] 

Connection timed out. The connection to a remote machine has timed out. If the connection 
timed out during execution of the function that reported this error (as opposed to timing 
out prior to the function being called), it is unspecified whether the function has completed 
some or all of the documented behavior associated with a successful completion of the 
function. 


[EPROTO] 

Protocol error. Some protocol error occurred. This error is device-specific, but is generally 
not related to a hardware failure. 

[EPROTONOSUPPORT] 

Protocol not supported. The protocol is not supported by the address family, or the protocol 
is not supported by the implementation. 

[EPROTOTYPE] 
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1324 

1325 

1326 

1327 MAN 

1328 

1329 

1330 

1331 MAN 

1332 

1333 

1334 

1335 

1336 [E AG AIN]. 

1337 [EXDEV] 

1338 Improper link. A link to a file on another file system was attempted. 

1339 2.3.1 Additional Error Numbers 

1340 Additional implementation-dependent error numbers may be defined in <errno.h>. 


or: 

Operation timed out. The time limit associated with the operation was exceeded before the 
operation completed. 

[ETXTBSY] 

Text file busy. An attempt was made to execute a pure-procedure program that is currently 
open for writing, or an attempt has been made to open for writing a pure-procedure 
program that is being executed. 

[EW OULDBLOCK] 

Operation would block. An operation on a socket marked as non-blocking has encountered 
a situation such as no data available that otherwise would have caused the function to 
suspend execution. 

A conforming implementation may assign the same values for [EWOULDBLOCK] and 
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1341 2.4 Signal Concepts 

1342 2.4.1 Signal Generation and Delivery 

1343 A signal is said to be generated for (or sent to) a process or thread when the event that causes the 

1344 signal first occurs. Examples of such events include detection of hardware faults, timer 

1345 rts expiration, signals generated via the sigevent structure and terminal activity, as well as 

1346 rts invocations of kiU() and sig queue ( ) functions. In some circumstances, the same event generates 

1347 signals for multiple processes. 

1348 At the time of generation, a determination is made whether the signal has been generated for the 

1349 process or for a specific thread within the process. Signals which are generated by some action 

1350 attributable to a particular thread, such as a hardware fault, are generated for the thread that 

1351 caused the signal to be generated. Signals that are generated in association with a process ID or 

1352 process group ID or an asynchronous event such as terminal activity are generated for the 

1353 process. 

1354 Each process has an action to be taken in response to each signal defined by the system (see 

1355 Section 2.4.2 on page 45). A signal is said to be delivered to a process when the appropriate action 

1356 for the process and signal is taken. A signal is said to be accepted by a process when the signal is 

1357 selected and returned by one of the sigivait () functions. 

1358 During the time between the generation of a signal and its delivery or acceptance, the signal is 

1359 said to be pending. Ordinarily, this interval cannot be detected by an application. However, a 

1360 signal can be blocked from delivery to a thread. If the action associated with a blocked signal is 

1361 anything other than to ignore the signal, and if that signal is generated for the thread, the signal 

1362 shall remain pending until it is unblocked, it is accepted when it is selected and returned by a 

1363 call to the sigivait () function, or the action associated with it is set to ignore the signal. Signals 

1364 generated for the process shall be delivered to exactly one of those threads within the process 

1365 which is in a call to a sigivait () function selecting that signal or has not blocked delivery of the 

1366 signal. If there are no threads in a call to a sigivait () function selecting that signal, and if all 

1367 threads within the process block delivery of the signal, the signal shall remain pending on the 

1368 process until a thread calls a sigivait () function selecting that signal, a thread unblocks delivery 

1369 of the signal, or the action associated with the signal is set to ignore the signal. If the action 

1370 associated with a blocked signal is to ignore the signal and if that signal is generated for the 

1371 process, it is unspecified whether the signal is discarded immediately upon generation or 

1372 remains pending. 

1373 Each thread has a signal mask that defines the set of signals currently blocked from delivery to it. 

1374 The signal mask for a thread is initialized from that of its parent or creating thread, or from the 

1375 corresponding thread in the parent process if the thread was created as the result of a call to 

1376 fork( ). The sigaction (), sigprocmask (), and s igsnspend() functions control the manipulation of the 

1377 signal mask. 

1378 The determination of which action is taken in response to a signal is made at the time the signal 

1379 is delivered, allowing for any changes since the time of generation. This determination is 

1380 independent of the means by which the signal was originally generated. If a subsequent 

1381 occurrence of a pending signal is generated, it is implementation-dependent as to whether the 

1382 rts signal is delivered or accepted more than once in circumstances other than those in which 

1383 queuing is required under the Realtime Signals Extension option. The order in which multiple, 

1384 simultaneously pending signals outside the range SIGRTMIN to SIGRTMAX are delivered to or 

1385 accepted by a process is unspecified. 

1386 When any stop signal (SIGSTOP, SIGTSTP, SIGTTIN, SIGTTOU) is generated for a process, any 

1387 pending SIGCONT signals for that process shall be discarded. Conversely, when SIGCONT is 

1388 generated for a process, all pending stop signals for that process shall be discarded. When 
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1389 SIGCONT is generated for a process that is stopped, the process shall be continued, even if the 

1390 SIGCONT signal is blocked or ignored. If SIGCONT is blocked and not ignored, it shall remain 

1391 pending until it is either unblocked or a stop signal is generated for the process. 

1392 An implementation shall document any condition not specified by this volume of 

1393 IEEE Std. 1003.1-200x under which the implementation generates signals. 

1394 rts Some signal-generating functions, such as high-resolution timer expiration, asynchronous I/O 

1395 completion, interprocess message arrival, and the sigqueue( ) function, support the specification 

1396 of an application-defined value, either explicitly as a parameter to the function or in a sigevent 

1397 structure parameter. The sigevent structure is defined in <signal.h> and contains at least the 

1398 following members: 


1399 


1400 

Member Type 

Member Name 

Description 

1401 

int 

sigev_notify 

Notification type. 

1402 

int 

sigev_signo 

Signal number. 

1403 

union sigval 

sigevjvalue 

Signal value. 

1404 

void(*) (unsigned sigval) 

sigev_notifyJunction 

Notification function. 

1405 

(pthread_attr_t*) 

sigev_notify_attributes 

Notification attributes. 


1406 

1407 

1408 

1409 

1410 

1411 

1412 

1413 

1414 

1415 

1416 

1417 

1418 


The sigev_notify member specifies the notification mechanism to use when an asynchronous 
event occurs. This volume of IEEE Std. 1003.1-200x defines the following values for the 
sigev_notify member: 

SIGEV_NONE No asynchronous notification shall be delivered when the event of 

interest occurs. 

SIGEV_SIGNAL The signal specified in sigev_signo shall be generated for the process when 
the event of interest occurs. If the implementation supports the Realtime 
Signals Extension option and if the SA_SIGINFO flag is set for that signal 
number, then the signal shall be queued to the process and the value 
specified in sigevjvalue shall be the si_value component of the generated 
signal. If SA_SIGINFO is not set for that signal number, it is unspecified 
whether the signal is queued and what value, if any, is sent. 

SIGEV_THREAD A notification function shall be called to perform notification. 


1419 An implementation may define additional notification mechanisms. 

1420 The sigev_signo member specifies the signal to be generated. The sigevjvalue member is the 

1421 application-defined value to be passed to the signal-catching function at the time of the signal 

1422 delivery or to be returned at signal acceptance as the sijvalue member of the siginfo_t structure. 


1423 The sigval union is defined in <signal.h> and contains at least the following members: 

1424 


1425 

Member Type 

Member Name 

Description 


1426 

int 

sival_int 

Integer signal value. 


1427 

void* 

sivaljptr 

Pointer signal value. 



1428 The sival_int member is used when the application-defined value is of type int; the sivaljptr 

1429 member is used when the application-defined value is a pointer. 

1430 When a signal is generated by the sigqueue( ) function or any signal-generating function that 

1431 supports the specification of an application-defined value, the signal shall be marked pending 

1432 and, if the SA_SIGINFO flag is set for that signal, the signal shall be queued to the process along 

1433 with the application-specified signal value. Multiple occurrences of signals so generated are 
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1434 queued in FIFO order. It is unspecified whether signals so generated are queued when the 

1435 SA_SIGINFO flag is not set for that signal. 


1436 

1437 

1438 

1439 


Signals generated by the kill( ) function or other events that cause signals to occur, such as 
detection of hardware faults, alarm () timer expiration, or terminal activity, and for which the 
implementation does not support queuing, have no effect on signals already queued for the 
same signal number. 


1440 When multiple unblocked signals, all in the range SIGRTMIN to SIGRTMAX, are pending, the 

1441 behavior shall be as if the implementation delivers the pending unblocked signal with the lowest 

1442 signal number within that range. No other ordering of signal delivery is specified. 


1443 If, when a pending signal is delivered, there are additional signals queued to that signal number, 

1444 the signal remains pending. Otherwise, the pending indication is reset. 


1445 Multi-threaded programs can use an alternate event notification mechanism. When a 

1446 notification is processed, and the sigev_notify member of the sigevent structure has the value 

1447 SIGEV_TF1READ, the function sigev_notify Junction is called with parameter sigevjvalue. 


1448 

1449 

1450 

1451 

1452 

1453 


The function shall be executed in an environment as if it were the start_routine for a newly 
created thread with thread attributes specified by sigev_notify_attributes. If sigev_notify_attributes 
is NULL, the behavior shall be as if the thread were created with the detachstate attribute set to 
PTHREAD_CREATE_DETACHED. Supplying an attributes structure with a detachstate attribute 
of PT H R E A DC R E AT E_J OIN A B L E results in undefined behavior. The signal mask of this 
thread is implementation-dependent. 


1454 2.4.2 Signal Actions 


1455 There are three types of action that can be associated with a signal: SIG_DFL, SIG_IGN, or a 

1456 pointer to a function. Initially, all signals shall be set to SIG_DFL or SIG_IGN prior to entry of 

1457 the main () routine (see the exec functions). The actions prescribed by these values are as follows: 


1458 SIG_DFL Signal-specific default action. 


1459 

1460 RTS 

1461 

1462 


The default actions for the signals defined in this volume of IEEE Std. 1003.1-200x 
are specified under <signal.h>. If the Realtime Signals Extension option is 
supported, the default actions for the realtime signals in the range SIGRTMIN to 
SIGRTMAX are to terminate the process abnormally. 


1463 

1464 

1465 

1466 

1467 

1468 

1469 

1470 

1471 


If the default action is to stop the process, the execution of that process is 
temporarily suspended. When a process stops, a SIGCHLD signal shall be 
generated for its parent process, unless the parent process has set the 
SA_NOCLDSTOP flag. While a process is stopped, any additional signals that are 
sent to the process shall not be delivered until the process is continued, except 
SIGKILL which always terminates the receiving process. A process that is a 
member of an orphaned process group shall not be allowed to stop in response to 
the SIGTSTP, SIGTTIN, or SIGTTOU signals. In cases where delivery of one of 
these signals would stop such a process, the signal shall be discarded. 


1472 

1473 

1474 

1475 

1476 


Setting a signal action to SIG_DFL for a signal that is pending, and whose default 
action is to ignore the signal (for example, SIGCHLD), shall cause the pending 
signal to be discarded, whether or not it is blocked. I 

The default action for SIGCONT is to resume execution at the point where the I 
process was stopped, after first handling any pending unblocked signals. I 
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1477 Notes to Reviewers 

1478 This section with side shading will not appear in the final copy. - Ed. 


1479 Dl, XSH, ERN 381 proposes "made available to queue other signals" be changed 

1480 to "and returned to the system for other use." 

1481 rts If the Realtime Signals Extension option is supported, any queued values pending 

1482 shall be discarded and the resources used to queue them shall be released and 

1483 made available to queue other signals. 


1484 SIG_IGN Ignore signal. 


1485 Delivery of the signal shall have no effect on the process. The behavior of a process 

1486 rts is undefined after it ignores a SIGFPE, SIGILL, SIGSEGV, or SIGBUS signal that 

1487 rts was not generated by kill(),sigqueue(), or raise(). 


1488 The system shall not allow the action for the signals SIGKILL or SIGSTOP to be set 

1489 to SIG_IGN. 


1490 Setting a signal action to SIG_IGN for a signal that is pending shall cause the 

1491 pending signal to be discarded, whether or not it is blocked. 

1492 If a process sets the action for the SIGCHLD signal to SIG_IGN, the behavior is 

1493 xsi unspecified, except as specified below. 


1494 If the action for the SIGCHLD signal is set to SIG_IGN, child processes of the 

1495 calling processes shall not be transformed into zombie processes when they 

1496 terminate. If the calling process subsequently waits for its children, and the process 

1497 has no unwaited-for children that were transformed into zombie processes, it shall 

1498 block until all of its children terminate, and ivait (), zvait3 (), waitid (), and waitpid () 

1499 shall fail and set errno to [ECHILD], 


1500 rts If the Realtime Signals Extension option is supported, any queued values pending 

1501 shall be discarded and the resources used to queue them shall be released and 

1502 made available to queue other signals. 


1503 pointer to a function 

1504 Catch signal. 


1505 

1506 

1507 

1508 


On delivery of the signal, the receiving process is to execute the signal-catching 
function at the specified address. After returning from the signal-catching function, 
the receiving process shall resume execution at the point at which it was 
interrupted. 


1509 If the SA_SIGINFO flag for the signal is cleared, the signal-catching function shall 

1510 be entered as a C-language function call as follows: 


1511 


void func (int signo) ; 


1512 xsi i rts If the SA_SIGINFO flag for the signal is set, the signal-catching function shall be 

1513 entered as a C-language function call as follows: 


1514 void func (int signo, siginfo_t *info, void ‘context) ; 

1515 

1516 

1517 


where func is the specified signal-catching function, signo is the signal number of 
the signal being delivered, and info is a pointer to a siginfo_t structure defined in 
<signal.h> containing at least the following members: 
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1518 


1519 

Member Type 

Member Name 

Description 

1520 

int 

si_signo 

Signal number 

1521 

int 

sijcode 

Cause of the signal 

1522 

union sigval 

si_value 

Signal value 


1523 

1524 

1525 


The si_signo member contains the signal number. This is the same as the signo 
parameter. The si_code member contains a code identifying the cause of the signal. 
The following values are defined for si_code: 


1526 Notes to Reviewers 


XSII RTS 


1527 

1528 

1529 

1530 

1531 

1532 


1533 RTS 

1534 RTS 

1535 


RTS 


RTS 


1536 

1537 

1538 

1539 

1540 

1541 

1542 

1543 RTS 

1544 

1545 

1546 

1547 XSI 

1548 RTS 

1549 

1550 

1551 

1552 

1553 

1554 

1555 

1556 

1557 

1558 

1559 


This section with side shading will not appear in the final copy. - Ed. 

The shading in this area needs some work. 

SI_USER The signal was sent by the kill() function. The implementation 

may set si_code to SI_USER if the signal was sent by the raise( ) or 
abort () functions or any similar functions provided as 
implementation extensions. 

SI_QUEUE The signal was sent by the sigcjueue( ) function. 

SI_TIMER The signal was generated by the expiration of a timer set by 

timer_settime (). 

SI_ASYNCIO The signal was generated by the completion of an asynchronous 
I/O request. 

SI_MESGQ The signal was generated by the arrival of a message on an 

empty message queue. 

If the signal was not generated by one of the functions or events listed above, the 
si_code shall be set to an implementation-dependent value that is not equal to any 
of the values defined above. 

If the Realtime Signals Extension is supported, and si_code is one of SI_QUEUE, 
SI_TIMER, SI_ASYNCIO, or SI_MESGQ, then si_valne contains the application- 
specified signal value. Otherwise, the contents of sijualue are undefined. 

The behavior of a process is undefined after it returns normally from a signal- 
catching function for a SIGBUS, SIGFPE, SIGILL, or SIGSEGV signal that was not 
generated by kill ( ),sigqueue( ),or raise (). 

The system shall not allow a process to catch the signals SIGKILL and SIGSTOP. 

If a process establishes a signal-catching function for the SIGCHLD signal while it 
has a terminated child process for which it has not waited, it is unspecified 
whether a SIGCHLD signal is generated to indicate that child process. 

When signal-catching functions are invoked asynchronously with process 
execution, the behavior of some of the functions defined by this volume of 
IEEE Std. 1003.1-200x is unspecified if they are called from a signal-catching 
function. 

The following table defines a set of functions that are either reentrant or not 
interruptible by signals and are async-signal-safe. Therefore applications may 
invoke them, without restriction, from signal-catching functions: 
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1560 Notes to Reviewers 

1561 This section with side shading will not appear in the final copy. - Ed. 

1562 The contents of the following tables need to be reviewed. 

1563 Base functions: 


1564 

_exit () 

fstat () 

raise () 

symlink () 

1565 

access () 

fsynci) 

read() 

sysconf () 

1566 

alarm () 

/truncate () 

readlink() 

tedrain () 

1567 

cfgetispeed () 

getegid() 

rename () 

tcflozv () 

1568 

cfgetospeed () 

getenid() 

rmdir() 

teflushe 

1569 

cfsetispeed() 

getgid () 

setgidi) 

tcgetattr() 

1570 

cfsetospeed{) 

getgronps () 

setpgid{) 

tegetpgrpe 

1571 

chdir() 

getpgrp () 

setsidQ 

tcsendbreak() 

1572 

chmod () 

getpid () 

setuidQ 

tcsetattr() 

1573 

chozvn () 

getppid () 

sigaction () 

tcsetpgrpl) 

1574 

close () 

getuid () 

sigaddset() 

time() 

1575 

create) 

kill () 

sigdelset() 

times e 

1576 

dnp () 

link() 

sigemptyset () 

umask() 

1577 

dnp2{) 

lseek() 

sigfillset () 

iinamei) 

1578 

execle() 

lstat{ ) 

sigismember() 

nnlink() 

1579 

execve() 

mkdir() 

signal () 

utime() 

1580 

fchmod () 

mkfifo () 

sigpending() 

wait{) 

1581 

fchown () 

open () 

sigprocmask() 

waitpid () 

1582 

fcntl() 

pathconf{) 

sigsuspend () 

write{) 

1583 

fork() 

pause() 

sleep () 


1584 

fpathconf() 

pipe() 

stat{) 


1585 

Realtime functions: 



1586 

aio_error() 

clock_gettime () 

sigpanse{) 

timer_getoverrnn () 

1587 

aio_retnrn{) 

fdatasync() 

sigynene() 

timer_gettime() 

1588 

aio_snspend{) 

sem_post() 

sigset e 

timer_settime() 


1589 All functions not in the above table are considered to be unsafe with respect to 

1590 signals. In the presence of signals, all functions defined by this volume of 

1591 IEEE Std. 1003.1-200x shall behave as defined when called from or interrupted by a 

1592 signal-catching function, with a single exception: when a signal interrupts an 

1593 unsafe function and the signal-catching function calls an unsafe function, the 

1594 behavior is undefined. 

1595 When a signal is delivered to a thread, if the action of that signal specifies termination, stop, or 

1596 continue, the entire process shall be terminated, stopped, or continued, respectively. 
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1597 2.4.3 Signal Effects on Other Functions 


1598 

1599 

1600 
1601 
1602 

1603 

1604 

1605 

1606 

1607 

1608 
1609 


Signals affect the behavior of certain functions defined by this volume of IEEE Std. 1003.1-200x if 
delivered to a process while it is executing such a function. If the action of the signal is to 
terminate the process, the process shall be terminated and the function shall not return. If the 
action of the signal is to stop the process, the process shall stop until continued or terminated. 
Generation of a SIGCONT signal for the process shall cause the process to be continued, and the 
original function shall continue at the point the process was stopped. If the action of the signal is 
to invoke a signal-catching function, the signal-catching function shall be invoked; in this case 
the original function is said to be interrupted by the signal. If the signal-catching function 
executes a return statement, the behavior of the interrupted function shall be as described 
individually for that function. Signals that are ignored shall not affect the behavior of any 
function; signals that are blocked shall not affect the behavior of any function until they are 
unblocked and then delivered, except as specified for the sigpending () and sigiuait () functions. 
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1610 2.5 Standard I/O Streams 

1611 A stream is associated with an external file (which may be a physical device) by opening a file, 

1612 which may involve creating a new file. Creating an existing file causes its former contents to be 

1613 discarded if necessary. If a file can support positioning requests, (such as a disk file, as opposed 

1614 to a terminal), then a file position indicator associated with the stream is positioned at the start 

1615 (byte number 0) of the file, unless the file is opened with append mode, in which case it is 

1616 implementation-dependent whether the file position indicator is initially positioned at the 

1617 beginning or end of the file. The file position indicator is maintained by subsequent reads, 

1618 writes, and positioning requests, to facilitate an orderly progression through the file. All input 

1619 takes place as if bytes were read by successive calls to fgetc(); all output takes place as if bytes 

1620 were written by successive calls to fputc (). 

1621 When a stream is unbuffered, bytes are intended to appear from the source or at the destination 

1622 as soon as possible; otherwise, bytes may be accumulated and transmitted as a block. When a 

1623 stream is fully buffered, bytes are intended to be transmitted as a block when a buffer is filled. 

1624 When a stream is line buffered, bytes are intended to be transmitted as a block when a newline 

1625 byte is encountered. Furthermore, bytes are intended to be transmitted as a block when a buffer 

1626 is filled, when input is requested on an unbuffered stream, or when input is requested on a line- 

1627 buffered stream that requires the transmission of bytes. Support for these characteristics is 

1628 implementation-dependent, and may be affected via setbuf( ) and setvbufi ). 

1629 A file may be disassociated from a controlling stream by closing the file. Output streams are 

1630 flushed (any unwritten buffer contents are transmitted) before the stream is disassociated from 

1631 the file. The value of a pointer to a FILE object is indeterminate after the associated file is closed 

1632 (including the standard streams). 

1633 A file may be subsequently reopened, by the same or another program execution, and its 

1634 contents reclaimed or modified (if it can be repositioned at its start). If the main () function 

1635 returns to its original caller, or if the exit{ ) function is called, all open files are closed (hence all 

1636 output streams are flushed) before program termination. Other paths to program termination, 

1637 such as calling abort (), need not close all files properly. 

1638 The address of the FILE object used to control a stream may be significant; a copy of a FILE 

1639 object need not necessarily serve in place of the original. 

1640 Notes to Reviewers 

1641 This section with side shading will not appear in the final copy. - Ed. 

1642 Dl, XSH, ERN 40 noted that we need to explicitly state how stderr is opened. Possible wording is 

1643 “stderr is opened for input and output, although it is expected that under normal circumstances 

1644 it will not be used for input/' 

1645 At program start-up, three streams are predefined and need not be opened explicitly: standard 

1646 input (for reading conventional input), standard output (for writing conventional output), and 

1647 standard error (for writing diagnostic output). When opened, the standard error stream is not 

1648 fully buffered; the standard input and standard output streams are fully buffered if and only if 

1649 the stream can be determined not to refer to an interactive device. 
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1650 2.5.1 Interaction of File Descriptors and Standard I/O Streams 

1651 Notes to Reviewers 

1652 This section with side shading will not appear in the final copy. - Ed. 

1653 We need to identify any additional CX shading in this section. 

1654 An open file description may be accessed through a file descriptor, which is created using 

1655 functions such as open() or pipe) ), or through a stream, which is created using functions such as 

1656 fopen() or popen(). Either a file descriptor or a stream shall be called a handle on the open file 

1657 description to which it refers; an open file description may have several handles. 

1658 Handles can be created or destroyed by explicit user action, without affecting the underlying 

1659 open file description. Some of the ways to create them include fcntl (), dnp(), fdopen(), fileno(), 

1660 and fork (). They can be destroyed by at least/dose(), close{ ), and the exec functions. 

1661 A file descriptor that is never used in an operation that could affect the file offset (for example, 

1662 read{), write ( ), or I seek ( )) is not considered a handle for this discussion, but could give rise to one 

1663 (for example, as a consequence otfdopen (), dnp ( ), or fork ()). 

1664 Notes to Reviewers 

1665 This section with side shading will not appear in the final copy. - Ed. 

1666 An alternative lead-in to the following sentence has been suggested as follows: "As an exception 

1667 to the exception, the file descriptor underlying a stream is not considered a handle, whether 

1668 created ..." (Ref Dl, XSH, ERN 42.) 

1669 This exception does not include the file descriptor underlying a stream, whether created with 

1670 fopen () or fdopen (), so long as it is not used directly by the application to affect the file offset. The 

1671 read() and write{ ) functions implicitly affect the file offset; lseek () explicitly affects it. 

1672 The result of function calls involving any one handle (the active handle) is defined elsewhere in 

1673 this volume of IEEE Std. 1003.1-200x, but if two or more handles are used, and any one of them is I 

1674 a stream, the application shall ensure that their actions are coordinated as described below. If I 

1675 this is not done, the result is undefined. I 

1676 A handle which is a stream is considered to be closed when either an fclose () or freopen () is 

1677 executed on it (the result of freopen ( ) is a new stream, which cannot be a handle on the same 

1678 open file description as its previous value), or when the process owning that stream terminates 

1679 with exit() or abort (). A file descriptor is closed by close (), _exit(), or the exec functions when 

1680 FD_CLOEXEC is set on that file descriptor. 

1681 For a handle to become the active handle, the application shall ensure that the actions below are I 

1682 performed between the last use of the handle (the current active handle) and the first use of the 

1683 second handle (the future active handle). The second handle then becomes the active handle. All 

1684 activity by the application affecting the file offset on the first handle shall be suspended until it I 

1685 again becomes the active file handle. (If a stream function has as an underlying function one that 

1686 affects the file offset, the stream function shall be considered to affect the file offset.) 

1687 The handles need not be in the same process for these rules to apply. 

1688 Note that after a fork( ), two handles exist where one existed before. The application shall ensure I 

1689 that, if both handles can ever be accessed, they are both in a state where the other could become I 

1690 the active handle first. The application shall prepare for a fork () exactly as if it were a change of I 

1691 active handle. (If the only action performed by one of the processes is one of the exec functions or 

1692 _exit( ) (not exit ( )), the handle is never accessed in that process.) 
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1693 For the first handle, the first applicable condition below applies. After the actions required 

1694 below are taken, if the handle is still open, the application can close it. 

1695 • If it is a file descriptor, no action is required. 

1696 • If the only further action to be performed on any handle to this open file descriptor is to close 

1697 it, no action need be taken. 

1698 • If it is a stream which is unbuffered, no action need be taken. 

1699 • If it is a stream which is line buffered, and the last byte written to the stream was a newline 

1700 (that is, as if a: 

1701 putc (' \n' ) 

1702 was the most recent operation on that stream), no action need be taken. 

1703 • If it is a stream which is open for writing or appending (but not also open for reading), the I 

1704 application shall either perform an /flush (), or the stream shall be closed. I 

1705 • If the stream is open for reading and it is at the end of the file (feof( ) is true), no action need 

1706 be taken. 

1707 • If the stream is open with a mode that allows reading and the underlying open file 

1708 description refers to a device that is capable of seeking, the application shall either perform I 

1709 an /flush (), or the stream shall be closed. I 

1710 Otherwise, the result is undefined. 

1711 For the second handle: 

1712 • If any previous active handle has been used by a function that explicitly changed the file 

1713 offset, except as required above for the first handle, the application shall perform an lseek( ) or I 

1714 fseek( ) (as appropriate to the type of handle) to an appropriate location. 

1715 If the active handle ceases to be accessible before the requirements on the first handle, above, 

1716 have been met, the state of the open file description becomes undefined. This might occur during 

1717 functions such as a fork () or _exit (). 

1718 The exec functions make inaccessible all streams that are open at the time they are called, 

1719 independent of which streams or file descriptors may be available to the new process image. 

1720 When these rules are followed, regardless of the sequence of handles used, implementations 

1721 shall ensure that an application, even one consisting of several processes, shall yield correct 

1722 results: no data shall be lost or duplicated when writing, and all data shall be written in order, 

1723 except as requested by seeks. It is implementation-dependent whether, and under what 

1724 conditions, all input is seen exactly once. 

1725 If the rules above are not followed, the result is unspecified. 

1726 Each function that operates on a stream is said to have zero or more underlying functions. This 

1727 means that the stream function shares certain traits with the underlying functions, but does not 

1728 require that there be any relation between the implementations of the stream function and its 

1729 underlying functions. 
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1730 2.5.2 Stream Orientation and Encoding Rules 

1731 For conformance to the ISO/IEC 9899:1990/Amendment 1:1995 (E), the definition of a stream 

1732 includes an orientation. After a stream is associated with an external file, but before any 

1733 operations are performed on it, the stream is without orientation. Once a wide-character 

1734 input/output function has been applied to a stream without orientation, the stream shall become 

1735 zvide-oriented. Similarly, once a byte input/output function has been applied to a stream without 

1736 orientation, the stream shall become byte-oriented. Only a call to the freopen() function or the 

1737 fivide( ) function can otherwise alter the orientation of a stream. 

1738 A successful call to freopen() shall remove any orientation. The three predefined streams standard 

1739 input, standard output, and standard error shall be unoriented at program start-up. 

1740 Byte input/output functions cannot be applied to a wide-oriented stream, and wide-character 

1741 input/output functions cannot be applied to a byte-oriented stream. The remaining stream 

1742 operations shall not affect and shall not be affected by a stream's orientation, except for the 

1743 following additional restrictions: 

1744 • Binary wide-oriented streams have the file positioning restrictions ascribed to both text and 

1745 binary streams. 

1746 • For wide-oriented streams, after a successful call to a file-positioning function that leaves the 

1747 file position indicator prior to the end-of-file, a wide-character output function can overwrite 

1748 a partial character; any file contents beyond the byte(s) written are henceforth undefined. 

1749 Each wide-oriented stream has an associated mbstate_t object that stores the current parse state 

1750 of the stream. A successful call to fgetpos () shall store a representation of the value of this 

1751 mbstate_t object as part of the value of the fpos_t object. A later successful call to fsetpos () using 

1752 the same stored fpos_t value shall restore the value of the associated mbstate_t object as well as 

1753 the position within the controlled stream. 

1754 Implementations that support multiple encoding rules associate an encoding rule with the 

1755 stream. The encoding rule shall be determined by the setting of the LCJCTYPE category in the 

1756 current locale at the time when the stream becomes wide-oriented. If a wide-character 

1757 input/output function is applied to a byte-oriented stream, the encoding rule used is undefined. 

1758 As with the stream's orientation, the encoding rule associated with a stream cannot be changed 

1759 once it has been set, except by a successful call to freopen () which clears the encoding rule and 

1760 resets the orientation to unoriented. 

1761 Although both text and binary wide-oriented streams are conceptually sequences of wide 

1762 characters, the external file associated with a wide-oriented stream is a sequence of (possibly 

1763 multibyte) characters generalized as follows: 

1764 • Multibyte encodings within files may contain embedded null bytes (unlike multibyte 

1765 encodings valid for use internal to the program). 

1766 • A file need not begin nor end in the initial shift state. 

1767 Moreover, the encodings used for characters may differ among files. Both the nature and choice 

1768 of such encodings are implementation-dependent. 

1769 The wide-character input functions read characters from the stream and convert them to wide 

1770 characters as if they were read by successive calls to th efgetzvc( ) function. Each conversion shall 

1771 occur as if by a call to the mbrtozvc( ) function, with the conversion state described by the stream's 

1772 cx own mbstate_t object, except the encoding rule associated with the stream is used instead of the 

1773 encoding rule implied by the LC_CTYPE category of the current locale. 

1774 The wide-character output functions convert wide characters to (possibly multibyte) characters 

1775 and write them to the stream as if they were written by successive calls to the fputzvc( ) function. 
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1776 Each conversion shall occur as if by a call to the wcrtomb() function, with the conversion state 

1777 cx described by the stream's own mbstate_t object, except the encoding rule associated with the 

1778 stream is used instead of the encoding rule implied by the LC_CTYPE category of the current 

1779 locale. 

1780 An encoding error shall occur if the character sequence presented to the underlying mbrtowc{) 

1781 function does not form a valid (generalized) character, or if the code value passed to the 

1782 underlying wcrtomb () function does not correspond to a valid (generalized) character. The 

1783 wide-character input/output functions and the byte input/output functions store the value of 

1784 the macro EILSEQ in errno if and only if an encoding error occurs. 
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1785 2.6 STREAMS 

1786 xsi STREAMS functionality is provided on implementations supporting the XSI STREAMS Option I 

1787 Group. I 

1788 xsr STREAMS provides a uniform mechanism for implementing networking services and other I 

1789 character-based I/O. The STREAMS function provides direct access to protocol modules. A 

1790 STREAM is typically a full-duplex connection between a process and an open device or pseudo- 

1791 device. However, since pipes may be STREAMS-based, a STREAM can be a full-duplex 

1792 connection between two processes. The STREAM itself exists entirely within the implementation 

1793 and provides a general character I/O function for processes. It optionally includes one or more 

1794 intermediate processing modules that are interposed between the process end of the STREAM 

1795 (STREAM head) and a device driver at the end of the STREAM (STREAM end). 

1796 STREAMS I/O is based on messages. Messages flow in both directions in a STREAM. A given 

1797 module need not understand and process every message in the STREAM, but every module in 

1798 the STREAM handles every message. Each module accepts messages from one of its neighbor 

1799 modules in the STREAM, and passes them to the other neighbor. For example, a line discipline 

1800 module may transform the data. Data flow through the intermediate modules is bidirectional, 

1801 with all modules handling, and optionally processing, all messages. There are three types of 

1802 messages: 

1803 • Data messages containing actual data for input or output 

1804 

1805 

1806 

1807 The function between the STREAM and the rest of the implementation is provided by a set of 

1808 functions at the STREAM head. When a process calls write(), piitmsg(), putpmsg (), or ioctl(), 

1809 messages are sent down the STREAM, and read( ), getmsg( ), or getpmsg( ) accepts data from the 

1810 STREAM and passes it to a process. Data intended for the device at the downstream end of the 

1811 STREAM is packaged into messages and sent downstream, while data and signals from the 

1812 device are composed into messages by the device driver and sent upstream to the STREAM 

1813 head. 

1814 When a STREAMS-based device is opened, a STREAM is created that contains two modules: the 

1815 STREAM head module and the STREAM end (driver) module. If pipes are STREAMS-based in 

1816 an implementation, when a pipe is created, two STREAMS are created, each containing a 

1817 STREAM head module. Other modules are added to the STREAM using ioctl(). New modules 

1818 are "pushed" onto the STREAM one at a time in last-in, first-out (LIFO) style, as though the 

1819 STREAM was a push-down stack. 


• Control data containing instructions for the STREAMS modules and underlying 
implementation 

• Other messages, which include file descriptors 


1820 Priority 

1821 xsr Message types are classified according to their queuing priority and may be normal (non- I 

1822 priority), priority, or high-priority messages. A message belongs to a particular priority band that 

1823 determines its ordering when placed on a queue. Normal messages have a priority band of 0 and 

1824 are always placed at the end of the queue following all other messages in the queue. High- 

1825 priority messages are always placed at the head of a queue, but are discarded if there is already a 

1826 high-priority message in the queue. Their priority band is ignored; they are high-priority by 

1827 virtue of their type. Priority messages have a priority band greater than 0. Priority messages are 

1828 always placed after any messages of the same or higher priority. High-priority and priority 

1829 messages are used to send control and data information outside the normal flow of control. By 

1830 convention, high-priority messages are not affected by flow control. Normal and priority 

1831 messages have separate flow controls. 
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1832 Message Parts 


1833 XSR 

1834 

1835 

1836 

1837 

1838 

1839 


A process may access STREAMS messages that contain a data part, control part, or both. The I 
data part is that information which is transmitted over the communication medium and the 
control information is used by the local STREAMS modules. The other types of messages are 
used between modules and are not accessible to processes. Messages containing only a data part 
are accessible via putmsg (), putpmsg (), getmsg (), getpmsg (), read{), or zvrite(). Messages 
containing a control part with or without a data part are accessible via calls to putmsg(), 
putpmsg (), getmsg (), or getpmsg (). 


1840 2.6.1 Accessing STREAMS 


1841 XSR 

1842 

1843 

1844 

1845 

1846 

1847 

1848 

1849 


A process accesses STREAMS-based files using the standard functions close (), ioctl {), getmsg (), I 
getpmsg (), open(), pipe(), poll(), putmsg(), pntpmsg{), read(), or write{). Refer to the applicable 
function definitions for general properties and errors. 

Calls to ioctl () are used to perform control functions with the STREAMS-based device associated 
with the file descriptor fildes. The arguments command and arg are passed to the STREAMS file 
designated by fildes and are interpreted by the STREAM head. Certain combinations of these 
arguments may be passed to a module or driver in the STREAM. 

Since these STREAMS requests are a subset of ioctl (), they are subject to the errors described 
there. 


1850 

1851 

1852 

1853 

1854 


STREAMS modules and drivers can detect errors, sending an error message to the STREAM 
head, thus causing subsequent functions to fail and set errno to the value specified in the 
message. In addition, STREAMS modules and drivers can elect to fail a particular ioctl () request 
alone by sending a negative acknowledgement message to the STREAM head. This causes just 
the pending ioctl () request to fail and set errno to the value specified in the message. 
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1855 2.7 

1856 XSI 

1857 

1858 

1859 

1860 
1861 
1862 

1863 

1864 


1865 Another interprocess communication facility is provided by functions in the Realtime Option 

1866 Group; see Section 2.8 on page 59. 


XSI Interprocess Communication 


The following message passing, semaphore, and shared memory services form an XSI 
interprocess communication facility. Certain aspects of their operation are common, and are 
described below. 





IPC Functions 



msgctl () semctl () shmctl () 

msgget () semget{) shmdt() 

msgrcv () semop () shmget() 

msgsndi ) shmat () 



1867 2.7.1 IPC General Description 


1868 XSI 

1869 

1870 

1871 

1872 

1873 

1874 

1875 

1876 

1877 

1878 

1879 

1880 
1881 
1882 

1883 

1884 

1885 

1886 

1887 

1888 


Each individual shared memory segment, message queue, and semaphore set is identified by a 
unique positive integer, called respectively a shared memory identifier, shmid, a semaphore 
identifier, semid, and a message queue identifier, msqid. The identifiers are returned by calls to 
shmget( ), semget{ ), and msgget{ ), respectively. 

Associated with each identifier is a data structure which contains data related to the operations 
which may be or may have been performed; see the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <sys/shm.h>, <sys/sem.h>, and <sys/msg.h> for their descriptions. 

Each of the data structures contains both ownership information and an ipc_perm structure (see 
the System Interface Definitions volume of IEEE Std. 1003.1-200x, <sys/ipc.h>) which are used in 
conjunction to determine whether or not read/write (read/alter for semaphores) permissions 
should be granted to processes using the IPC facilities. The mode member of the ipc_perm 
structure acts as a bit field which determines the permissions. 


The values of the bits are given below in octal notation. 


Bit 

Meaning 



0400 

Read by user. 



0200 

Write by user. 



0040 

Read by group. 



0020 

Write by group. 



0004 

Read by others. 



0002 

Write by others. 



1889 

1890 

1891 

1892 


The name of the ipc_perm structure is shmjperm, semjperm, or msgjperm, depending on which 
service is being used. In each case, read and write/alter permissions are granted to a process if 
one or more of the following are true (" xxx" is replaced by slim , sem, or msg, as appropriate): 

• The process has appropriate privileges. 


1893 

1894 

1895 

1896 

1897 

1898 


• The effective user ID of the process matches xxx_perm.cmd or xxx_perm.uid in the data 
structure associated with the IPC identifier, and the appropriate bit of the user field in 
xxx_perm.mode is set. 

• The effective user ID of the process does not match xxx_perm.cmd or xxxjperm.uid but the 
effective group ID of the process matches xxxjperm.cgid or xxxjperm.gid in the data structure 
associated with the IPC identifier, and the appropriate bit of the group field in xxxjperm.mode 
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1899 is set. 

1900 • The effective user ID of the process does not match xxx_perm.cuid or xxx_perm.uid and the 

1901 effective group ID of the process does not match xxx_perm.cgid or xxx_perm.gid in the data 

1902 structure associated with the IPC identifier, but the appropriate bit of the other field in 

1903 xxxjperm.mode is set. 

1904 Otherwise, the permission is denied. 
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1905 2.8 Realtime 


1906 Notes to Reviewers 

1907 This section with side shading will not appear in the final copy. - Ed. 

1908 Re Dl, XSH, ERN 46: Frank will identify better shading for this section. 

1909 This section defines functions to support the source portability of applications with realtime 

1910 requirements. The presence of many of these functions is dependent on support for 

1911 implementation options described in the text. 

1912 The specific functional areas included in this section and their scope include the following. Full 

1913 definitions of these terms can be found in the System Interface Definitions volume of 

1914 IEEE Std. 1003.1-200x, Chapter 3, Definitions. 

1915 • Semaphores 

1916 • Process Memory Locking 

1917 • Memory Mapped Files and Shared Memory Objects 

1918 • Priority Scheduling 

1919 • Realtime Signal Extension 

1920 • Timers 

1921 • Interprocess Communication 

1922 • Synchronized Input and Output 

1923 • Asynchronous Input and Output 

1924 All the realtime functions defined in this volume of IEEE Std. 1003.1-200x are portable, although 

1925 some of the numeric parameters used by an implementation may have hardware dependencies. 


1926 2.8.1 Realtime Signal Generation and Delivery 

1927 rts Realtime signal generation and delivery is dependent on support for the Realtime Signals I 

1928 Extension option. I 


1929 

1930 

1931 

1932 

1933 

1934 

1935 

1936 

1937 

1938 

1939 

1940 


Some signal-generating functions, such as high-resolution timer expiration, asynchronous I/O 
completion, interprocess message arrival, and the sigqueue () function, support the specification 
of an application-defined value, either explicitly as a parameter to the function or in a sigevent 
structure parameter. The sigevent structure shall be defined in the System Interface Definitions 
volume of IEEE Std. 1003.1-200x, <signal.h> and shall contain at least the following members: 


Member Type 

Member Name 

Description 

int 

int 

union sigval 

void(*) (unsigned sigval) 

(pthread_attr_t*) 

sigev_notify 
sigev_signo 
sigev_value 
sigev_notify Junction 
sigev_notify_attributes 

Notification type. 

Signal number. 

Signal value. 
Notification. 
Notification attributes. 


1941 The sigev_notify member specifies the notification mechanism to use when an asynchronous 

1942 event occurs. This volume of IEEE Std. 1003.1-200x defines the following values for the 

1943 sigev_notify member: 
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1944 SIGEV_NONE No asynchronous notification shall be delivered when the event of 

1945 interest occurs. 

1946 SIGEV_SIGNAL A queued signal, with an application-defined value, shall be generated 

1947 when the event of interest occurs. 


1948 SIGEV_THREAD A notification function shall be called to perform notification. 

1949 An implementation may define additional notification mechanisms. 

1950 The sigev_signo member specifies the signal to be generated. The sigev_value member is the 

1951 application-defined value to be passed to the signal-catching function at the time of the signal 

1952 delivery as the sijvalue member of the siginfo_t structure. 


1953 

1954 

1955 

1956 

1957 

1958 


The sigval union is defined in the System Interface Definitions volume of IEEE Std. 1003.1-200x, 
<signal.h> and contains at least the following members: 


Member Type 

Member Name 

Description 

int 

void * 

sival_int 

sival_ptr 

Integer signal value. 
Pointer signal value. 


1959 The sival_int member is used when the application-defined value is of type int; the sival_ptr 

1960 member is used when the application-defined value is a pointer. 

1961 When a signal is generated by the sigqueue( ) function, or any signal-generating function that 

1962 supports the specification of an application-defined value, the signal shall be marked pending 

1963 and, if the SA_SIGINFO flag is set for that signal, the signal shall be queued to the process along 

1964 with the application-specified signal value. Multiple occurrences of signals so generated are 

1965 queued in FIFO order. It is unspecified whether signals so generated shall be queued when the 

1966 SA_SIGINFO flag is not set for that signal. 

1967 Signals generated by the kill() function or other events that cause signals to occur, such as 

1968 detection of hardware faults, alarm () timer expiration, or terminal activity, and for which the 

1969 implementation does not support queuing, shall have no effect on signals already queued for the 

1970 same signal number. 

1971 When multiple unblocked signals, all in the range {SIGRTMIN} to {SIGRTMAX}, are pending, 

1972 the behavior shall be as if the implementation delivers the pending unblocked signal with the 

1973 lowest signal number within that range. No other ordering of signal delivery is specified. 

1974 If, when a pending signal is delivered, there are additional signals queued to that signal number, 

1975 the signal shall remain pending; otherwise, the pending indication shall be reset. 


1976 2.8.2 Asynchronous I/O 

1977 aio Asynchronous I/O is dependent on support of the Asynchronous Input and Output option. 

1978 An asynchronous I/O control block structure aiocb is used in many asynchronous I/O 

1979 functions. It is defined in the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

1980 <aio.h> and has at least the following members: 
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1981 


1982 

Member Type 

Member Name 

Description 

1983 

int 

aioffildes 

File descriptor. 

1984 

off_t 

aio_offset 

File offset. 

1985 

volatile void* 

aioffmf 

Focation of buffer. 

1986 

size_t 

aio_nbytes 

Fength of transfer. 

1987 

int 

aio_reqprio 

Request priority offset. 

1988 

struct sigevent 

aio_sigevent 

Signal number and value. 

1989 

int 

aio_lio_opcode 

Operation to be performed. 


1990 The aioffildes element is the file descriptor on which the asynchronous operation is performed. 

1991 If 0_APPEND is not set for the file descriptor aioffildes , and if aioffildes is associated with a 

1992 device that is capable of seeking, then the requested operation takes place at the absolute 

1993 position in the file as given by aio_offset , as if l seek () were called immediately prior to the 

1994 operation with an offset argument equal to aio_offset and a whence argument equal to SEEK_SET. 

1995 If 0_APPEND is set for the file descriptor, or if aioffildes is associated with a device that is 

1996 incapable of seeking, write operations append to the file in the same order as the calls were 

1997 made, with the following exception: under implementation-dependent circumstances, such as 

1998 operation on a multiprocessor or when requests of differing priorities are submitted at the same 

1999 time, the ordering restriction may be relaxed. After a successful call to enqueue an asynchronous 

2000 I/O operation, the value of the file offset for the file is unspecified. The aio_nbytes and aiojbuf 

2001 elements are the same as the nbyte and buf arguments defined by read () and write ( ), respectively. 

2002 If _POSIX_PRIORITIZED_IO and _POSIX_PRIORITY_SCHEDULING are defined, then 

2003 asynchronous I/O is queued in priority order, with the priority of each asynchronous operation 

2004 based on the current scheduling priority of the calling process. The aio_reqprio member can be 

2005 used to lower (but not raise) the asynchronous I/O operation priority and is within the range 

2006 zero through {AIO_PRIO_DELTA_MAX}, inclusive. Unless both _POSIX_PRIORITIZED_IO and 

2007 _POSIX_PRIORITY_SCHEDULING are defined, the order of processing asynchronous I/O 

2008 requests is unspecified. When both _POSIX_PRIORITIZED_IO and 

2009 _POSIX_PRIORITY_SCHEDULING are defined, the order of processing of requests submitted 

2010 by processes whose schedulers are not SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC is 

2011 unspecified. The priority of an asynchronous request is computed as (process scheduling 

2012 priority) minus aio_reqprio . The priority assigned to each asynchronous I/O request is an 

2013 indication of the desired order of execution of the request relative to other asynchronous I/O 

2014 requests for this file. If _POSIX_PRIORITIZED_IO is defined, requests issued with the same 

2015 priority to a character special file are processed by the underlying device in FIFO order; the order 

2016 of processing of requests of the same priority issued to files that are not character special files is 

2017 unspecified. Numerically higher priority values indicate requests of higher priority. The value of 

2018 aio_reqprio has no effect on process scheduling priority. When prioritized asynchronous I/O 

2019 requests to the same file are blocked waiting for a resource required for that I/O operation, the 

2020 higher-priority I/O requests shall be granted the resource before lower-priority I/O requests are 

2021 granted the resource. The relative priority of asynchronous I/O and synchronous I/O is 

2022 implementation-dependent. If _POSIX_PRIORITIZED_IO is defined, the implementation shall 

2023 define for which files I/O prioritization is supported. 

2024 The aio_sigevent determines how the calling process shall be notified upon I/O completion, as 

2025 specified in Section 2.4.1 on page 43. If aio_sigevent.sigev_notify is SIGEV_NONE, then no signal 

2026 shall be posted upon I/O completion, but the error status for the operation and the return status 

2027 for the operation shall be set appropriately. 

2028 The aio_lio_opcode field is used only by the liojistio () call. The liojistio () call allows multiple 

2029 asynchronous I/O operations to be submitted at a single time. The function takes as an 

2030 argument an array of pointers to aiocb structures. Each aiocb structure indicates the operation to 
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2031 be performed (read or write) via the aio_lio_opcode field. 

2032 The address of the aiocb structure is used as a handle for retrieving the error status and return 

2033 status of the asynchronous operation while it is in progress. 

2034 The aiocb structure and the data buffers associated with the asynchronous I/O operation are 

2035 being used by the system for asynchronous I/O while, and only while, the error status of the 

2036 asynchronous operation is equal to EINPROGRESS. Applications shall not modify the aiocb I 

2037 structure while the structure is being used by the system for asynchronous I/O. 

2038 The return status of the asynchronous operation is the number of bytes transferred by the I/O 

2039 operation. If the error status is set to indicate an error completion, then the return status is set to 

2040 the return value that the corresponding read(), zvrite(), or fsync{) call would have returned. 

2041 When the error status is not equal to EINPROGRESS, the return status shall reflect the return 

2042 status of the corresponding synchronous operation. 

2043 2.8.3 Memory Management 

2044 Notes to Reviewers 

2045 This section with side shading will not appear in the final copy. - Ed. 

2046 The MPR-related text needs additional work to cater for when MPR is not supported. Note that 

2047 .la rewrites a lot of this. See also Dl, XSH, ERN 46. 

2048 mf Memory management is dependent on support of the Memory Mapped Files option. I 

2049 ml Memory locking is dependent on support of the Process Memory Locking option. I 

2050 Range memory locking and memory mapping operations are defined in terms of pages. I 

2051 Implementations may restrict the size and alignment of range lockings and mappings to be on 

2052 page-size boundaries. The page size, in bytes, is the value of the configurable system variable 

2053 {PAGESIZE}. If an implementation has no restrictions on size or alignment, it may specify a 1- 

2054 byte page size. 

2055 Memory locking guarantees the residence of portions of the address space. It is 

2056 implementation-dependent whether locking memory guarantees fixed translation between 

2057 virtual addresses (as seen by the process) and physical addresses. Per-process memory locks are 

2058 not inherited across a fork (), and all memory locks owned by a process are unlocked upon exec or 

2059 process termination. Unmapping of an address range removes any memory locks established on 

2060 that address range by this process. 

2061 Memory mapped files provide a mechanism that allows a process to access files by directly 

2062 incorporating file data into its address space. Once a file is mapped into a process address space, 

2063 the data can be manipulated as memory. If more than one process maps a file, its contents are 

2064 shared among them. If the mappings allow shared write access, then data written into the 

2065 memory object through the address space of one process appears in the address spaces of all 

2066 processes that similarly map the same portion of the memory object. 

2067 shm Shared memory objects are named regions of storage that may be independent of the file system 

2068 and can be mapped into the address space of one or more processes to allow them to share the 

2069 associated memory. 

2070 shm An unlink () of a file or shm_unlink () of a shared memory object, while causing the removal of the 

2071 name, does not unmap any mappings established for the object. Once the name has been 

2072 removed, the contents of the memory object are preserved as long as it is referenced. The 

2073 memory object remains referenced as long as a process has the memory object open or has some 

2074 area of the memory object mapped. 
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2075 tym Implementations may support the Typed Memory Objects option without supporting the I 

2076 Memory Mapped Files option or the Shared Memory Objects option. Typed memory objects are I 

2077 implementation-configurable named storage pools accessible from one or more processors in a I 

2078 system, each via one or more ports, such as backplane buses, LANs, I/O channels, and so on. I 

2079 Each valid combination of a storage pool and a port is identified through a name that is defined I 

2080 at system configuration time, in an implementation-dependent manner; the name may be I 

2081 independent of the file system. Using this name, a typed memory object can be opened and I 

2082 mapped into process address space. For a given storage pool and port, it is necessary to support I 

2083 both dynamic allocation from the pool as well as mapping at an application-supplied offset I 

2084 within the pool; when dynamic allocation has been performed, subsequent deallocation must be I 

2085 supported. Lastly, accessing typed memory objects from different ports requires a method for I 

2086 obtaining the offset and length of contiguous storage of a region of typed memory (dynamically I 

2087 allocated or not); this allows typed memory to be shared among processes and/or processors I 

2088 while being accessed from the desired port. I 

2089 Notes to Reviewers 

2090 This section zvith side shading zvill not appear in the final copy. - Ed. 

2091 Dl, XSH, ERN 49 proposes new wording for the following paragraph: "When an object is 

2092 mapped, various application accesses to the mapped region may result in signals. In this context, 

2093 SIGBUS is used to indicate an error using the mapped object, and SIGSEGV is used to indicate a 

2094 protections violation or misuse of an address: 

2095 • A mapping may be restricted to disallow some types of access. 

2096 • Write attempts to memory that was mapped without write access, or any access to memory 

2097 mapped PROT_NONE, shall result in a SIGSEGV signal. 

2098 • References to unmapped addresses shall result in a SIGSEGV signal. 

2099 • Reference to whole pages within the mapping, but beyond the current length of the object I 

2100 shall result in a SIGBUS signal. 

2101 • The size of the object is unaffected by access beyond the end of the object (even if a SIGBUS is 

2102 not generated. 

2103 mpr Mapping may be restricted to disallow some types of access. References to whole pages within I 

2104 the mapping, but beyond the current length of an object, result in a SIGBUS signal. SIGBUS is 

2105 used in this context to indicate an error using the object. The size of the object is unaffected by 

2106 access beyond the end of the object. Write attempts to memory that was mapped without write 

2107 access, or any access to memory mapped PROT_NONE, result in a SIGSEGV signal. SIGSEGV is 

2108 used in this context to indicate a mapping error. References to unmapped addresses result in a 

2109 SIGSEGV signal. I 

2110 2.8.4 Process Scheduling I 

2111 Scheduling Policies I 

2112 Scheduling policies are dependent on support of the Process Scheduling option. I 

2113 The scheduling semantics described in this volume of IEEE Std. 1003.1-200x are defined in terms 

2114 of a conceptual model that contains a set of thread lists. No implementation structures are 

2115 necessarily implied by the use of this conceptual model. It is assumed that no time elapses 

2116 during operations described using this model, and therefore no simultaneous operations are 

2117 possible. This model discusses only processor scheduling for runnable threads, but it should be 

2118 noted that greatly enhanced predictability of realtime applications result if the sequencing of 
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2119 other resources takes processor scheduling policy into account. 

2120 There is, conceptually, one thread list for each priority. Any runnable thread may be on any 

2121 thread list. Multiple scheduling policies shall be provided. Each non-empty thread list is 

2122 ordered, contains a head as one end of its order, and a tail as the other. The purpose of a 

2123 scheduling policy is to define the allowable operations on this set of lists (for example, moving 

2124 threads between and within lists). 

2125 Each process shall be controlled by an associated scheduling policy and priority. These 

2126 parameters may be specified by explicit application execution of the sched_setschednler() or 

2127 sched_setparam() functions. 

2128 Each thread shall be controlled by an associated scheduling policy and priority. These 

2129 parameters may be specified by explicit application execution of the pthread_setschedparam() 

2130 function. 

2131 Associated with each policy is a priority range. Each policy definition shall specify the minimum 

2132 priority range for that policy. The priority ranges for each policy may but need not overlap the 

2133 priority ranges of other policies. 

2134 A conforming implementation shall select the thread that is defined as being at the head of the 

2135 highest priority non-empty thread list to become a running thread, regardless of its associated 

2136 policy. This thread is then removed from its thread list. 

2137 Four scheduling policies are specifically required. Other implementation-dependent scheduling 

2138 policies may be defined. The following symbols are defined in the System Interface Definitions 

2139 volume of IEEE Std. 1003.1-200x, <sched.h>: 

2140 SCHED_FIFO First in, first out (FIFO) scheduling policy. 

2141 SCHED_RR Round robin scheduling policy. 

2142 ss SCHED_SPORADIC Sporadic server scheduling policy. 

2143 SCHED_OTHER Another scheduling policy. 

2144 The values of these symbols shall be distinct. 


2145 SCHED_FIFO 

2146 Conforming implementations shall include a scheduling policy called the FIFO scheduling 

2147 policy. 

2148 Threads scheduled under this policy are chosen from a thread list that is ordered by the time its 

2149 threads have been on the list without being executed; generally, the head of the list is the thread 

2150 that has been on the list the longest time, and the tail is the thread that has been on the list the 

2151 shortest time. 


2152 Under the SCHED_FIFO policy, the modification of the definitional thread lists is as follows: 


2153 1. When a running thread becomes a preempted thread, it becomes the head of the thread list 

2154 for its priority. 


2155 2. When a blocked thread becomes a runnable thread, it becomes the tail of the thread list for 

2156 its priority. 


2157 

2158 

2159 


3. When a running thread calls the sched_setscheduler () function, the process specified in the 
function call is modified to the specified policy and the priority specified by the param 
argument. 
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2160 4. When a running thread calls the sched_setparam() function, the priority of the process 

2161 specified in the function call is modified to the priority specified by the param argument. 

2162 5. When a running thread calls the pthread_setschedparam() function, the thread specified in 

2163 the function call is modified to the specified policy and the priority specified by the param 

2164 argument. 

2165 6. If a thread whose policy or priority has been modified is a running thread or is runnable, it 

2166 then becomes the tail of the thread list for its new priority. 

2167 7. When a running thread issues the sched_yield () function, the thread becomes the tail of the 

2168 thread list for its priority. 

2169 8. At no other time is the position of a thread with this scheduling policy within the thread 

2170 lists affected. 

2171 For this policy, valid priorities shall be within the range returned by the sched_getapriority_max {) 

2172 and sched_get_priority_min () functions when SCHED_FIFO is provided as the parameter. 

2173 Conforming implementations shall provide a priority range of at least 32 priorities for this 

2174 policy. 

2175 SCHED_RR 

2176 Conforming implementations shall include a scheduling policy called the round robin scheduling 

2177 policy. This policy is identical to the SCHED_FIFO policy with the additional condition that 

2178 when the implementation detects that a running thread has been executing as a running thread 

2179 for a time period of the length returned by the sched_rr_get_interval () function or longer, the 

2180 thread shall become the tail of its thread list and the head of that thread list shall be removed 

2181 and made a running thread. 

2182 The effect of this policy is to ensure that if there are multiple SCHED_RR threads at the same 

2183 priority, one of them does not monopolize the processor. An application should not rely only on 

2184 the use of SCHED_RR to ensure application progress among multiple threads if the application 

2185 includes threads using the SCFIED_FIFO policy at the same or higher priority levels or 

2186 SCFIED_RR threads at a higher priority level. 

2187 A thread under this policy that is preempted and subsequently resumes execution as a running 

2188 thread completes the unexpired portion of its round robin interval time period. 

2189 For this policy, valid priorities shall be within the range returned by the sched_get_priority_max () 

2190 and sched_get jpriority_min () functions when SCFIED_RR is provided as the parameter. 

2191 Conforming implementations shall provide a priority range of at least 32 priorities for this 

2192 policy. 

2193 SCHED_SPORADIC 

2194 ss If _POSIX_SPORADIC_SERVER or _POSIX_THREAD_SPORADIC_SERVER is defined, the 

2195 implementation shall include a scheduling policy identified by the value SCPtED_SPORADIC. 

2196 The sporadic server policy is based primarily on two parameters: the replenishment period and the 

2197 available execution capacity. The replenishment period is given by the sched_ss_repl_period 

2198 member of the sched_param structure. The available execution capacity is initialized to the 

2199 value given by the sched_ss_mit_budget member of the same parameter. The sporadic server 

2200 policy is identical to the SCFIED_FIFO policy with some additional conditions that cause the 

2201 thread's assigned priority to be switched between the values specified by the sched_priority and 

2202 sched_ss_low_priority members of the sched_param structure. 
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2203 

2204 

2205 

2206 

2207 

2208 

2209 

2210 
2211 

2212 

2213 

2214 

2215 

2216 

2217 

2218 

2219 

2220 
2221 
2222 

2223 

2224 

2225 

2226 

2227 

2228 

2229 

2230 

2231 

2232 

2233 

2234 

2235 

2236 

2237 

2238 

2239 

2240 

2241 

2242 

2243 

2244 

2245 

2246 

2247 

2248 

2249 

2250 


The priority assigned to a thread using the sporadic server scheduling policy is determined in 
the following manner: if the available execution capacity is greater than zero and the number of 
pending replenishment operations is strictly less than sched_ss_max_repl , the thread is assigned 
the priority specified by schedjpriority ; otherwise, the assigned priority shall be 
sched_ss_low_priority. If the value of schedjpriority is less than or equal to the value of 
sched_ss_low_priority, the results are undefined. When active, the thread shall belong to the 
thread list corresponding to its assigned priority level, according to the mentioned priority 
assignment. The modification of the available execution capacity and, consequently of the 
assigned priority, is done as follows: 

1. When the thread at the head of the schedjpriority list becomes a running thread, its 
execution time shall be limited to at most its available execution capacity, plus the 
resolution of the execution time clock used for this scheduling policy. This resolution shall 
be implementation-dependent. 

2. Each time the thread is inserted at the tail of the list associated with schedjpriority — 
because as a blocked thread it became runnable with priority schedjpriority or because a 
replenishment operation was performed—the time at which this operation is done is 
posted as the activation_time. 

3. When the running thread with assigned priority equal to schedjpriority becomes a 
preempted thread, it becomes the head of the thread list for its priority, and the execution 
time consumed is subtracted from the available execution capacity. If the available 
execution capacity would become negative by this operation, it shall be set to zero. 

4. When the running thread with assigned priority equal to schedjpriority becomes a blocked 
thread, the execution time consumed is subtracted from the available execution capacity, 
and a replenishment operation is scheduled, as described below. If the available execution 
capacity would become negative by this operation, it shall be set to zero. 

5. When the running thread with assigned priority equal to schedjpriority reaches the limit 
imposed on its execution time, it becomes the tail of the thread list for 
sched_ss_low_priority , the execution time consumed is subtracted from the available 
execution capacity (which becomes zero), and a replenishment operation is scheduled, as 
described below. 

6. Each time a replenishment operation is scheduled, the amount of execution capacity to be 
replenished, replenish jimonnt, is set equal to the execution time consumed by the thread 
since the activation_time . The replenishment is scheduled to occur at activation_time plus 
sched_ss_repl_period. If the scheduled time obtained is before the current time, the 
replenishment operation is carried out immediately. Notice that there may be several 
replenishment operations pending at the same time, each of which will be serviced at its 
respective scheduled time. Notice also that with the above rules, the number of 
replenishment operations simultaneously pending for a given thread that is scheduled 
under the sporadic server policy shall not be greater than sched_ssjnaxjrepl. 

7. A replenishment operation consists of adding the corresponding replenishjimonnt to the 
available execution capacity at the scheduled time. If as a consequence of this operation 
the execution capacity would become larger than schedjssjnitialjbudget, it shall be 
rounded down to a value equal to schedjssjnitialjbudget. Additionally, if the thread was 
runnable or running, and with assigned priority equal to sched_ss_low_priority , then it 
becomes the tail of the thread list for schedjpriority. 

Execution time is defined in Section 2.2.2 on page 28. 

For this policy, changing the value of a CPU-time clock via clock_settime( ) shall have no effect on 
its behavior. 
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2251 For this policy, valid priorities shall be within the range returned by the sched_get_priority_min () I 

2252 and sched_get_priority_max() functions when SCHED_SPORADIC is provided as the parameter. I 

2253 Conforming implementations shall provide a priority range of at least 32 distinct priorities for I 

2254 this policy. I 

2255 SCHED_OTHER 

2256 Conforming implementations shall include one scheduling policy identified as SCHED_OTHER 

2257 (which may execute identically with either the FIFO or round robin scheduling policy). The 

2258 effect of scheduling threads with the SCFIED_OTHER policy in a system in which other threads I 

2259 ss are executing under SCHED_FIFO, SCFIED_RR, or SCHED_SPORADIC is implementation- I 

2260 dependent. I 

2261 This policy is defined to allow conforming applications to be able to indicate that they no longer 

2262 need a realtime scheduling policy in a portable manner. 

2263 For threads executing under this policy, the implementation shall use only priorities within the 

2264 range returned by the sched_get_priority_max () and sched_get_priority_min () functions when 

2265 SCFIED_OTHER is provided as the parameter. 

2266 2.8.5 Clocks and Timers 

2267 Clocks and timers are dependent on support of the Timers option. 

2268 The <time.h> header defines the types and manifest constants used by the timing facility. 

2269 Time Value Specification Structures 

2270 Many of the timing facility functions accept or return time value specifications. A time value 

2271 structure timespec specifies a single time value and includes at least the following members: 

2272 

2273 

2274 

2275 


2276 The tv_nsec member is only valid if greater than or equal to zero, and less than the number of 

2277 nanoseconds in a second (1,000 million). The time interval described by this structure is ( tv_sec * 

9 J 

2278 10 + tv_nsec) nanoseconds. 

2279 A time value structure itimerspec specifies an initial timer value and a repetition interval for use 

2280 by the per-process timer functions. This structure includes at least the following members: 

2281 
2282 

2283 

2284 


2285 If the value described by it_value is non-zero, it indicates the time to or time of the next timer 

2286 expiration (for relative and absolute timer values, respectively). If the value described by it_value 

2287 is zero, the timer shall be disarmed. 

2288 If the value described by it_interval is non-zero, it specifies an interval to be used in reloading the 

2289 timer when it expires; that is, a periodic timer is specified. If the value described by it_interval is 

2290 zero, the timer is disarmed after its next expiration; that is, a one-shot timer is specified. 


Member Type 

Member Name 

Description 

struct timespec 
struct timespec 

it_interval 

it_value 

Timer period. 
Timer expiration. 


Member Type 

Member Name 

Description 

time_t 

long 

tv_sec 

tv_nsec 

Seconds. 

Nanoseconds. 
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2291 Timer Event Notification Control Block 

2292 rts Per-process timers may be created that notify the process of timer expirations by queuing a 

2293 realtime extended signal. The sigevent structure, defined in the System Interface Definitions 

2294 volume of IEEE Std. 1003.1-200x, <signal.h>, is used in creating such a timer. The sigevent 

2295 structure contains the signal number and an application-specific data value to be used when 

2296 notifying the calling process of timer expiration events. 

2297 Manifest Constants 

2298 The following constants are defined in the System Interface Definitions volume of 

2299 IEEE Std. 1003.1-200x, <time.h>: 

2300 CLOCK_REALTIME The identifier for the system-wide realtime clock. 

2301 TIMER_ABSTIME Flag indicating time is absolute with respect to the clock associated 

2302 with a timer. 

2303 mon CLOCK_MONOTONIC The identifier for the system-wide monotonic clock, which is defined 

2304 as a clock whose value cannot be set via clock_settime( ) and which 

2305 cannot have backward clock jumps. The maximum possible clock 

2306 jump shall be implementation-dependent. 

2307 mon The maximum allowable resolution for the CLOCK_REALTIME and the 

2308 CLOCK_MONOTONIC clocks and all time services based on these clocks is represented by 

2309 j_POSIX_CLOCKRES_MIN} and is defined as 20ms (1/50 of a second). Implementations may 

2310 support smaller values of resolution for these clocks to provide finer granularity time bases. The 

2311 actual resolution supported by an implementation for a specific clock is obtained using the 

2312 clock_getres () function. If the actual resolution supported for a time service based on one of these 

2313 clocks differs from the resolution supported for that clock, the implementation shall document 

2314 this difference. 

2315 mon The minimum allowable maximum value for the CLOCK_REALTIME and the 

2316 CLOCK_MONOTONIC clocks and all absolute time services based on them is the same as that 

2317 defined by the ISO C standard for the time_t type. If the maximum value supported by a time 

2318 service based on one of these clocks differs from the maximum value supported by that clock, 

2319 the implementation shall document this difference. 

2320 Execution Time Monitoring 

2321 cpt If _POSIX_CPUTIME is defined, process CPU-time clocks shall be supported in addition to the 

2322 clocks described in Manifest Constants. 

2323 tct If _POSIX_THREAD_CPUTIME is defined, thread CPU-time clocks shall be supported. 

2324 cpt i tct CPU-time clocks measure execution or CPU time, which is defined in the System Interface 

2325 Definitions volume of IEEE Std. 1003.1-200x, Section 3.120, CPU Time (Execution Time). The 

2326 mechanism used to measure execution time is described in the System Interface Definitions 

2327 volume of IEEE Std. 1003.1-200x, Section 4.4, Measurement of Execution Time. 

2328 cpt If _POSIX_CPUTIME is defined, the following constant of the type clockid_t shall be defined in 

2329 <time.h>: 

2330 CLOCK_PROCESS_CPUTIME_ID 

2331 When this value of the type clockid_t is used in a clock() or timer* () function call, it is 

2332 interpreted as the identifier of the CPU-time clock associated with the process making the 

2333 function call. 

2334 
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2335 tct If _POSIX_THREAD_CPUTIME is defined, the following constant of the type clockid_t shall be 

2336 defined in <time.h>: 

2337 

2338 

2339 

2340 

2341 


CLOCK_THREAD_CPUTIME_ID 

When this value of the type clockid_t is used in a clock() or timer*() function call, it is 
interpreted as the identifier of the CPU-time clock associated with the thread making the 
function call. 
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2342 2.9 Threads 

2343 This section defines functionality to support multiple flows of control, called threads, within a 

2344 process. For the definition of threads, see Section 1.1 on page 1. 

2345 thr Threads are dependent on support of the Threads option. I 

2346 The specific functional areas covered by threads and their scope includes: I 

2347 • Thread management: the creation, control, and termination of multiple flows of control in the 

2348 same process under the assumption of a common shared address space 

2349 • Synchronization primitives optimized for tightly coupled operation of multiple control flows 

2350 in a common, shared address space 

2351 • Harmonization of the threads functions with the existing POSIX system interfaces 

2352 2.9.1 Supported Functions 

2353 xsi On systems claiming XSI System Interfaces conformance, the following symbolic constants are I 

2354 always defined: 

2355 _POSIX_READER_WRITER_LOCKS 

2356 _POSIX_THREAD_ATTR_STACKADDR 

2357 _POSIX_THREAD_ATTR_STACKSIZE 

2358 _POSIX_THREAD_PROCESS_SHARED 

2359 _POSIX_THREADS 

2360 Therefore, the following threads functions are always supported: 


2361 

pthread_atfork() 

pthread_detach () 

2362 

pthread_attr_destroy () 

pthreadjqual () 

2363 

pthread_attr_getdetachstate() 

pthread_exit () 

2364 

pthread_attr_getschedparam () 

pthread_getspecific () 

2365 

pthread_attr_getstackaddr() 

pthread_join () 

2366 

pthread_attr_getstacksize () 

pthread_key_create () 

2367 

pthread_attr_init () 

pthread_key_delete() 

2368 

pthread_attr_setdetachstate () 

pthreadjdll () 

2369 

pthread_attr_setschedparam () 

pthread_mutex_destroy() 

2370 

pthread_attr_setstackaddr () 

pthread_mutex_init{) 

2371 

pthread_attr_setstacksize() 

pthread_mutex_lock() 

2372 

pthread_cancel () 

pthread_mntex_trylock{) 

2373 

pthread_cleanup_pop () 

pthread_mutex_unlock{) 

2374 

pthread_cleanupjpush{) 

pthreadjnutexattr_destroy {) 

2375 

pthread_cond_broadcast () 

pthread_mutexattr_getpshared () 

2376 

pthread_cond_destroy () 

pthreadjnutexattr_init () 

2377 

pthread_cond_init () 

pthreadjnutexattr_setpshared () 

2378 

pthread_cond_signal () 

pthread_once() 

2379 

pthread_cond_timedivait () 

pthread_self() 

2380 

pthread_cond_zvait () 

pthread_setcancelstate () 

2381 

pthread_condattr_destroy() 

pthread_setcanceltype() 

2382 

pthread_condattr_getpshared() 

pthread_setspecific () 

2383 

pthread_condattr_init () 

pthread_sigmask () 

2384 

pthread_condattr_setpshared() 

pthread_testcancel () 

2385 

pthread_create() 

sigwait() 
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2386 


2387 XSI 

2388 

2389 

2390 

2391 

2392 

2393 

2394 

2395 

2396 

2397 XSI 

2398 

2399 

pthread_attr_getgnardsize () 
ptliread_attr_setgnardsize( ) 
pthread_getconcurrency( ) 
pthread_mutexattr_gettype () 
pthread_mutexattr_settype( ) 
pthread_rivlock_destroy () 
pthread_nvlock_init( ) 
pthread_rzvlock_rdlock( ) 
pthread_rivlock_tryrdlock( ) 

pthread_rzvlock_tryivrlock( ) 
pthread_riulock_iinlock{) 
pthread_rzvlock_zvrlock( ) 
pthread_nvlockattr_destroy () 
pthread_rzvlockattr_getpshared () 
pthread_rivlockattr_init() 
pthread_rivlockattr_setpshared () 
pthread_set concurrency () 

On systems claiming XSI System Interfaces conformance, the symbolic constant 
_POSIX_THREAD_SAFE_FUNCTIONS is always defined. Therefore, the following functions are 
always supported: 




2400 

asctime_r() 

getpwnam_r{) 

2401 

ctime_r () 

getpwuid_r() 

2402 

flockfile () 

gmtime_r( ) 

2403 

ftrylockfile () 

localtime_r( ) 

2404 

funlockfile () 

putc_unlocked() 

2405 

getc_nnlocked() 

putchar_unlocked{ ) 

2406 

getchar_unlocked{ ) 

rand_r( ) 

2407 

getgrgid_r( ) 

readdir_r( ) 

2408 

getgrnam_r( ) 

strtok_r( ) 

2409 

The following threads functions 

are only supported on systems claiming XSI System Interfaces 

2410 

conformance if the Realtime 

Threads Option Group is supported (see <REFERENCE 

2411 

UNDEFINED>(realtime_threads) ): 




2412 

pthread_attr_getinheritsched () 

pth read_vmtex_getprioceil ing() 

2413 

pthread_attr_getschedpolicy( ) 

pthread_mntex_setprioceiling{) 

2414 

pthread_attr_getscope( ) 

pthread_mutexattr_getprioceiling( ) 

2415 

pthread_attr_setinheritsched () 

pthread_mutexattr_getprotocol () 

2416 

pthread_attr_setschedpolicy( ) 

pthread_mutexattr_setprioctiling{ ) 

2417 

pthread_attr_setscope( ) 

pthread_mntexattr_setprotocol () 

2418 

pthread_getschedparam() 

pthread_setschedparam () 


2419 


2420 2.9.2 Thread-Safety 

2421 All functions defined by this volume of IEEE Std. 1003.1-200x shall be thread-safe, except that 

2422 the following functions need not be thread-safe. 


2423 

asctime() 

getliostbyname() 

getprotobynumber() 

inet_ntoa() 

ttyname() 

2424 

ctime () 

gethostent{) 

getprotoent () 

localtime() 

unsetenv{) 

2425 

getc_unlocked () 

getlogin () 

getpwnami) 

putc_unlocked{) 

wcstombs{) 

2426 

getclmr_unlocked () 

getnetbyaddr () 

getpwnid{) 

putchar_unlocked () 

zvctomb () 
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2427 

2428 

2429 

2430 

getenv() 
getgrgid () 
getgrnam () 
gethostbyaddr () 

getnetbyname{) 
getnetent () 
get opt () 

getprotobyname () 

getservbyname () 
getserz’byport () 
getservent() 
gmtime() 

rand() 
readdir () 
setenv () 
strtok () 


2431 XSI 

basename () 

dbmjopen () 

fcvt() 

hdestroyO 

setgrent{) 

2432 

cat gets () 

dbm_store () 

gcvt() 

hsearch() 

setkey{) 

2433 

crypt () 

dirname () 

getdate() 

I64a{) 

setpzvent() 

2434 

dbm_clearerr() 

dlerror () 

getenz’ () 

lgamma() 

setutxent{) 

2435 

dbm_close () 

drand48 () 

getgrent{) 

lrand48() 

strerror () 

2436 

dbm_delete () 

ecvt() 

getpzvent{) 

mrand48 () 


2437 

dbm_error() 

encrypt () 

getutxent() 

nl_langinfo () 


2438 

dbmjetch () 

endgrent () 

getutxidQ 

ptsname () 


2439 

dbmjirstkeyl) 

endpzvent() 

getutxline() 

pntenv() 


2440 

dbm_nextkey () 

endntxent{) 

hcreate () 

pntutxline () 



2441 

2442 The read () function need not be thread-safe when reading from a pipe, FIFO, or terminal device. I 

2443 Notes to Reviewers I 

2444 This section zvith side shading zvill not appear in the final copy. - Ed. I 

2445 What about the semantics on a socket? I 

2446 The ctermid() and tmpnam () functions need not be thread-safe if passed a NULL argument. The I 

2447 zvcrtombi ) and zvcsrtombs( ) functions need not be thread-safe if passed a NULL ps argument. 

2448 Implementations shall provide internal synchronization as necessary in order to satisfy this 

2449 requirement. 

2450 2.9.3 Thread IDs 

2451 Although implementations may have thread IDs that are unique in a system, applications 

2452 should only assume that thread IDs are usable and unique within a single process. The effect of 

2453 calling any of the functions defined in this volume of IEEE Std. 1003.1-200x and passing as an 

2454 argument the thread ID of a thread from another process is unspecified. A conforming 

2455 implementation is free to reuse a thread ID after the thread terminates if it was created with the 

2456 detachstate attribute set to PTHREAD_CREATE_DETACHED or if pthread_detach() or 

2457 pthread_join ( ) has been called for that thread. If a thread is detached, its thread ID is invalid for 

2458 use as an argument in a call to pthread_detach () or pthread_join (). 

2459 2.9.4 Thread Implementation Models (Informative) I 

2460 There are various thread implementation models. At one end of the spectrum is the “library- I 

2461 thread model". In such a model, the threads of a process are not visible to the operating system 

2462 kernel, and the threads are not kernel scheduled entities. The process is the only kernel 

2463 scheduled entity. The process is scheduled onto the processor by the kernel according to the 

2464 scheduling attributes of the process. The threads are scheduled onto the single kernel scheduled 

2465 entity (the process) by the runtime library according to the scheduling attributes of the threads. I 

2466 A problem with this model is that it constrains concurrency. Since there is only one kernel 

2467 scheduled entity (namely, the process), only one thread per process can execute at a time. If the 

2468 thread that is executing blocks on I/O, then the whole process blocks. 
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2469 At the other end of the spectrum is the "kernel-thread model". In this model, all threads are 

2470 visible to the operating system kernel. Thus, all threads are kernel scheduled entities, and all 

2471 threads can concurrently execute. The threads are scheduled onto processors by the kernel 

2472 according to the scheduling attributes of the threads. The drawback to this model is that the 

2473 creation and management of the threads entails operating system calls, as opposed to subroutine 

2474 calls, which makes kernel threads heavier weight than library threads. 

2475 Hybrids of these two models are common. A hybrid model offers the speed of library threads 

2476 and the concurrency of kernel threads. In hybrid models, a process has some (relatively small) 

2477 number of kernel scheduled entities associated with it. It also has a potentially much larger 

2478 number of library threads associated with it. Some library threads may be bound to kernel 

2479 scheduled entities, while the other library threads are multiplexed onto the remaining kernel 

2480 scheduled entities. There are two levels of thread scheduling: 

2481 1. The runtime library manages the scheduling of (unbound) library threads onto kernel I 

2482 scheduled entities. 

2483 2. The kernel manages the scheduling of kernel scheduled entities onto processors. 

2484 For this reason, a hybrid model is referred to as a two-level threads scheduling model. In this model, 

2485 the process can have multiple concurrently executing threads; specifically, it can have as many 

2486 concurrently executing threads as it has kernel scheduled entities. 

2487 2.9.5 Thread Mutexes 

2488 A thread that has blocked shall not prevent any unblocked thread that is eligible to use the same 

2489 processing resources from eventually making forward progress in its execution. Eligibility for 

2490 processing resources is determined by the scheduling policy. 

2491 A thread becomes the owner of a mutex, m, when one of the following occurs: 

2492 • It returns successfully from pthread_mutex_lock( ) with m as the mutex argument. 

2493 • It returns successfully from pthread_mutex_trylock( ) with m as the mutex argument. 

2494 • It returns (successfully or not) from pthread_cond_wait{) with m as the mutex argument 

2495 (except as explicitly indicated otherwise for certain errors). 

2496 • It returns (successfully or not) from pthread_cond_timedwait( ) with m as the mutex argument 

2497 (except as explicitly indicated otherwise for certain errors). 

2498 The thread remains the owner of m until one of the following occurs: 

2499 • It executes pthread_tnutex_unlock( ) with m as the mutex argument 

2500 • It blocks in a call to pthread_cond_wait () with m as the mutex argument. 

2501 • It blocks in a call to pthread_cond_timedwait( ) with m as the mutex argument. 

2502 The implementation behaves as if at all times there is at most one owner of any mutex. 

2503 A thread that becomes the owner of a mutex is said to have acquired the mutex and the mutex is 

2504 said to have become locked ; when a thread gives up ownership of a mutex it is said to have 

2505 released the mutex and the mutex is said to have become unlocked . I 
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2506 2.9.6 Thread Scheduling I 

2507 Thread Scheduling Attributes I 

2508 Thread scheduling attributes are dependent on support of the Thread Execution Scheduling I 

2509 option. 

2510 In support of the scheduling function, threads have attributes which are accessed through the 

2511 pthread_attr_t thread creation attributes object. 

2512 The contentionscope attribute defines the scheduling contention scope of the thread to be either 

2513 PTHREAD_SCOPE_PROCESS or PTHREAD_SCOPE_SYSTEM. 

2514 The inheritsched attribute specifies whether a newly created thread is to inherit the scheduling 

2515 attributes of the creating thread or to have its scheduling values set according to the other 

2516 scheduling attributes in the pthread_attr_t object. 

2517 The schedpolicy attribute defines the scheduling policy for the thread. The schedparam attribute 

2518 defines the scheduling parameters for the thread. The interaction of threads having different 

2519 policies within a process is described as part of the definition of those policies. 

2520 If the _POSIX_THREAD_PRIORITY_SCHEDULING option is defined, and the schedpolicy 

2521 attribute specifies one of the priority-based policies defined under this option, the schedparam 

2522 attribute contains the scheduling priority of the thread. A conforming implementation ensures 

2523 that the priority value in schedparam is in the range associated with the scheduling policy when 

2524 the thread attributes object is used to create a thread, or when the scheduling attributes of a 

2525 thread are dynamically modified. The meaning of the priority value in schedparam is the same as 

2526 that of priority . 

2527 tsp If _POSIX_THREAD_SPORADIC_SERVER is defined, the schedparam attribute supports four I 

2528 new members that are used for the sporadic server scheduling policy. These members are I 

2529 sched_ss_low_priority , sched_ss_repl_period, sched_ss_init_budget , and sched_ss_max_repl . The I 

2530 meaning of these attributes is the same as in the definitions that appear under Section 2.8.4 on I 

2531 page 63. I 

2532 When a process is created, its single thread has a scheduling policy and associated attributes I 

2533 equal to the process' policy and attributes. The default scheduling contention scope value is 

2534 implementation-dependent. The default values of other scheduling attributes are 

2535 implementation-dependent. I 

2536 Thread Scheduling Contention Scope I 

2537 The scheduling contention scope of a thread defines the set of threads with which the thread I 

2538 competes for use of the processing resources. The scheduling operation selects at most one I 

2539 thread to execute on each processor at any point in time and the thread's scheduling attributes 

2540 (for example, priority), whether under process scheduling contention scope or system scheduling 

2541 contention scope, are the parameters used to determine the scheduling decision. 

2542 The scheduling contention scope, in the context of scheduling a mixed scope environment, 

2543 effects threads as follows: 

2544 • A thread created with PTHREAD_SCOPE_SYSTEM scheduling contention scope contends 

2545 for resources with all other threads in the same scheduling allocation domain relative to their 

2546 system scheduling attributes. The system scheduling attributes of a thread created with 

2547 PTHREAD_SCOPE_SYSTEM scheduling contention scope are the scheduling attributes with 

2548 which the thread was created. The system scheduling attributes of a thread created with 

2549 PTHREAD_SCOPE_PROCESS scheduling contention scope are the implementation- 
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2550 dependent mapping into system attribute space of the scheduling attributes with which the 

2551 thread was created. 

2552 • Threads created with PTHREAD_SCOPE_PROCESS scheduling contention scope contend 

2553 directly with other threads within their process that were created with 

2554 PTHREAD_SCOPE_PROCESS scheduling contention scope. The contention is resolved 

2555 based on the threads' scheduling attributes and policies. It is unspecified how such threads 

2556 are scheduled relative to threads in other processes or threads with 

2557 PTH RE A DSCOPE_S YSTEM scheduling contention scope. 

2558 • Conforming implementations shall support the PTHREAD_SCOPE_PROCESS scheduling 

2559 contention scope, the PTHREAD_SCOPE_SYSTEM scheduling contention scope, or both. 

2560 Scheduling Allocation Domain I 

2561 Implementations shall support scheduling allocation domains containing one or more I 

2562 processors. It should be noted that the presence of multiple processors does not automatically 

2563 indicate a scheduling allocation domain size greater than one. Conforming implementations on 

2564 multiprocessors may map all or any subset of the CPUs to one or multiple scheduling allocation 

2565 domains, and could define these scheduling allocation domains on a per-thread, per-process, or 

2566 per-system basis, depending on the types of applications intended to be supported by the 

2567 implementation. The scheduling allocation domain is independent of scheduling contention 

2568 scope, as the scheduling contention scope merely defines the set of threads with which a thread I 

2569 contends for processor resources, while scheduling allocation domain defines the set of I 

2570 processors for which it contends. The semantics of how this contention is resolved among 

2571 threads for processors is determined by the scheduling policies of the threads. 

2572 The choice of scheduling allocation domain size and the level of application control over 

2573 scheduling allocation domains is implementation-dependent. Conforming implementations may 

2574 change the size of scheduling allocation domains and the binding of threads to scheduling 

2575 allocation domains at any time. 

2576 For application threads with scheduling allocation domains of size equal to one, the scheduling 

2577 rules defined for SCHED_FIFO and SCHED_RR shall be used; see Scheduling Policies on page 

2578 63. All threads with system scheduling contention scope, regardless of the processes in which 

2579 they reside, compete for the processor according to their priorities. Threads with process 

2580 scheduling contention scope compete only with other threads with process scheduling 

2581 contention scope within their process. 

2582 For application threads with scheduling allocation domains of size greater than one, the rules I 

2583 tsp defined for SCHED_FIFO, SCHED_RR, and SCHED_SPORADIC shall be used in an I 

2584 implementation-dependent manner. Each thread with system scheduling contention scope I 

2585 competes for the processors in its scheduling allocation domain in an implementation- I 

2586 dependent manner according to its priority. Threads with process scheduling contention scope 

2587 are scheduled relative to other threads within the same scheduling contention scope in the 

2588 process. I 

2589 tsp If _POSIX_THREAD_SPORADIC_SERVER is defined, the rules defined for SCHED_SPORADIC I 

2590 in Scheduling Policies on page 63 shall be used in an implementation-dependent manner for I 

2591 application threads whose scheduling allocation domain size is greater than one. I 
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2592 Scheduling Documentation I 

2593 If _POSIX_PRIORITY_SCHEDULING is defined, then any scheduling policies beyond I 

2594 tsp SCHED_OTHER, SCHED_FIFO, SCHED_RR, and SCHED_SPORADIC, as well as the effects of I 

2595 the scheduling policies indicated by these other values, and the attributes required in order to I 

2596 support such a policy, are implementation-dependent. Furthermore, the implementation shall I 

2597 document the effect of all processor scheduling allocation domain values supported for these I 

2598 policies. I 

2599 2.9.7 Thread Cancelation 

2600 The thread cancelation mechanism allows a thread to terminate the execution of any other 

2601 thread in the process in a controlled manner. The target thread (that is, the one that is being 

2602 canceled) is allowed to hold cancelation requests pending in a number of ways and to perform 

2603 application-specific cleanup processing when the notice of cancelation is acted upon. 

2604 Cancelation is controlled by the cancelation control functions. Each thread maintains its own 

2605 cancelability state. Cancelation may only occur at cancelation points or when the thread is 

2606 asynchronously cancelable. 

2607 The thread cancelation mechanism described in this section depends upon programs having set 

2608 deferred cancelability state, which is specified as the default. Applications shall also carefully I 

2609 follow static lexical scoping rules in their execution behavior. For example, use of setjmpi), 

2610 return, goto, and so on, to leave user-defined cancelation scopes without doing the necessary 

2611 scope pop operation results in undefined behavior. 

2612 Use of asynchronous cancelability while holding resources which potentially need to be released 

2613 may result in resource loss. Similarly, cancelation scopes may only be safely manipulated 

2614 (pushed and popped) when the thread is in the deferred or disabled cancelability states. 

2615 2.9.7.1 Cancelability States 

2616 The cancelability state of a thread determines the action taken upon receipt of a cancelation 

2617 request. The thread may control cancelation in a number of ways. 

2618 Each thread maintains its own cancelability state, which may be encoded in two bits: 

2619 1. Cancelability-Enable: When cancelability is PTHREAD_CANCEL_DISABLE (as defined in 

2620 the System Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h>), 

2621 cancelation requests against the target thread are held pending. By default, cancelability is 

2622 set to PTHREAD_CANCEL_ENABLE (as defined in <pthread.h>). 

2623 2. Cancelability Type: When cancelability is enabled and the cancelability type is 

2624 PTHREAD_CANCEL_ASYNCHRONOUS (as defined in <pthread.h>), new or pending 

2625 cancelation requests may be acted upon at any time. When cancelability is enabled and the 

2626 cancelability type is PTHREAD_CANCEL_DEFERRED (as defined in <pthread.h>), 

2627 cancelation requests are held pending until a cancelation point (see below) is reached. If 

2628 cancelability is disabled, the setting of the cancelability type has no immediate effect as all 

2629 cancelation requests are held pending; however, once cancelability is enabled again the 

2630 new type is in effect. The cancelability type is PTHREAD_CANCEL_DEFERRED in all 

2631 newly created threads including the thread in which main () was first invoked. 
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2632 2.9.7.2 Cancelation Points 

2633 Cancelation points occur when a thread is executing the following functions: 


2634 

accept () 

mq_timedsend() 

putpmsg() 

sigsuspendO 

2635 

aio_snspend() 

msgrcv () 

pzvrite () 

sigtimedivait () 

2636 

clock_nanosleep() 

msgsnd() 

read() 

sigwait () 

2637 

close () 

msync () 

readi’O 

sigzvaitinfo () 

2638 

connect() 

nanosleep () 

recv() 

sleep 0 

2639 

creat() 

open () 

recvfrom () 

system () 

2640 

fcntl() 2 

panse{) 

recvmsg () 

tcdrain () 

2641 

fsync{) 

poll() 

select 0 

asleep () 

2642 

getmsg() 

preadO 

sem_timedivait () 

zvait () 

2643 

getpmsgi) 

pthread_cond_timedwait () 

sem_ivait () 

zcflz'f3 () 

2644 

lockf() 

pthread_cond_wait () 

send() 

zvaitid () 

2645 

mq_receive () 

pthread_join () 

sendmsg() 

zvaitpid () 

2646 

mq_send{) 

pthread_testcancel () 

sendtoO 

zurite{) 

2647 

mq_timedreceive{) 

putmsgi) 

sigpanse{) 

zvritez>() 


2648 - 

2649 2. When the cmd argument is F_SETLKW. 
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2650 A cancelation point may also occur when a thread is executing the following functions: 


2651 

cat close () 

fscanfi) 

getpivnid_r () 

putchar_nnlocked() 

2652 

catgets () 

fseek () 

gets () 

puts{) 

2653 

catopen () 

fseeko () 

getservbyname() 

pntntxlinei) 

2654 

closedir () 

fsetpos () 

getservbyport{) 

pntzvc{) 

2655 

closelog() 

ftell () 

getservent () 

pntzvchar{) 

2656 

ctermid () 

ftello () 

getntxent() 

readdir() 

2657 

dbm_close () 

ftzv() 

getntxid() 

readdir_r() 

2658 

dbm_delete( ) 

fwprintfl) 

getntxline{) 

removei) 

2659 

dbmjetch () 

fzvrite() 

getivc() 

rename{) 

2660 

dbm_nextkey () 

fwscanf{) 

getzvchar() 

rezuind () 

2661 

dbm_open () 

getc() 

getzvd() 

rezvinddiri) 

2662 

dbm_store () 

getc_nnlocked{) 

glob() 

scanfi) 

2663 

diclose () 

get char () 

iconv_close() 

seekdir{) 

2664 

dlopen () 

getchar_nnlocked() 

iconv_open () 

semop() 

2665 

endgrent() 

getcwd{) 

ioctl () 

setgrent{) 

2666 

endhostent() 

getdate() 

lseek () 

sethostent() 

2667 

endnetent() 

getgrent() 

mks tempi ) 

setnetent{) 

2668 

endprotoent () 

getgrgid () 

nftzv() 

setprotoent{) 

2669 

endpzvent() 

getgrgid_r() 

opendiri) 

setpzvent{) 

2670 

endservent () 

getgrnam() 

openlogi) 

setservent() 

2671 

endntxent{) 

getgrnam_r() 

pclose{) 

setntxenti) 

2672 

/close () 

gethostbyaddr() 

perrori) 

strerrori ) 

2673 

fcntl() 3 

gethostbyname() 

popen () 

syslogi) 

2674 

/flush () 

gethostent() 

posix_fadvise () 

tmpfilei) 

2675 

fgetc () 

ge t host name () 

posix_fallocate() 

tmpnam{) 

2676 

fgetpos () 

getlogin () 

posix_madvise{) 

tty name () 

2677 

/gets () 

getlogin_r () 

posix_spazvn () 

ttyname_r() 

2678 

fgetivc () 

getnetbyaddr() 

posix_spazvnp () 

nngetc{) 

2679 

fgetivs () 

getnetbyname() 

posix_typed_mem_open () 

nngetzvc{) 

2680 

/open () 

getnetent() 

printfi) 

nnlinki) 

2681 

/print /() 

getprotobyname() 

pthread_rzvlock_rdlock{) 

vfprintfi) 

2682 

fputci) 

getprotobynnmber() 

pthread_rzvlock_timedrdlock() 

vfivprintfi) 

2683 

fputs{) 

getprotoent() 

pthread_rzvlock_timedzvrlock () 

z’printf() 

2684 

fpntzvc() 

getpivent{) 

pthread_rzvlock_zvrlock () 

z’zvprintfi ) 

2685 

fpntivs () 

getpivnam() 

putc{) 

zvprintfi) 

2686 

fread () 

getpzvnam_r () 

putc_unlocked{) 

zvscanfi ) 

2687 

/reopen () 

getpividd() 

putchar{) 



2688 An implementation shall not introduce cancelation points into any other functions specified in 

2689 this volume of IEEE Std. 1003.1-200x. 

2690 The side effects of acting upon a cancelation request while suspended during a call of a function 

2691 are the same as the side effects that may be seen in a single-threaded program when a call to a 

2692 function is interrupted by a signal and the given function returns [EINTR], Any such side effects 

2693 occur before any cancelation cleanup handlers are called. 

2694 - 

2695 3. For any value of the cmd argument. 
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2696 Whenever a thread has cancelability enabled and a cancelation request has been made with that 

2697 thread as the target and the thread calls pthread_testcancel(), then the cancelation request is acted 

2698 upon before pthread_testcancel{) returns. If a thread has cancelability enabled and the thread has 

2699 a cancelation request pending and the thread is suspended at a cancelation point waiting for an 

2700 event to occur, then the cancelation request shall be acted upon. However, if the thread is 

2701 suspended at a cancelation point and the event that it is waiting for occurs before the cancelation 

2702 request is acted upon, it is unspecified whether the cancelation request is acted upon or whether 

2703 the request remains pending and the thread resumes normal execution. 

2704 2.9.73 Thread Cancelation Cleanup Handlers 

2705 Each thread maintains a list of cancelation cleanup handlers. The programmer uses the 

2706 pthread_cleanup_push () and pthread_cleannp_pop() functions to place routines on and remove 

2707 routines from this list. 

2708 When a cancelation request is acted upon, the routines in the list are invoked one by one in LIFO 

2709 sequence; that is, the last routine pushed onto the list (Last In) is the first to be invoked (First 

2710 Out). The thread invokes the cancelation cleanup handler with cancelation disabled until the last 

2711 cancelation cleanup handler returns. When the cancelation cleanup handler for a scope is 

2712 invoked, the storage for that scope remains valid. If the last cancelation cleanup handler returns, 

2713 thread execution is terminated and a status of PTHREAD_CANCELED is made available to any 

2714 threads joining with the target. The symbolic constant PTHREAD_CANCELED expands to a 

2715 constant expression of type (void*) whose value matches no pointer to an object in memory nor 

2716 the value NULL. 

2717 The cancelation cleanup handlers are also invoked when the thread calls pthread_exit(). 

2718 A side effect of acting upon a cancelation request while in a condition variable wait is that the 

2719 mutex is re-acquired before calling the first cancelation cleanup handler. In addition, the thread 

2720 is no longer considered to be waiting for the condition and the thread shall not have consumed 

2721 any pending condition signals on the condition. 

2722 A cancelation cleanup handler cannot exit via longjmp () or siglongjmp (). 

2723 2 .9.7.4 Async-Cancel Safety 

2724 The pthread_cancel(), pthread_setcancelstate( ), and pthread_setcanceltype( ) functions are defined to 

2725 be async-cancel safe. 

2726 No other functions in this volume of IEEE Std. 1003.1-200x are required to be async-cancel-safe. 

2727 2.9.8 Thread Read-Write Locks 

2728 Notes to Reviewers 

2729 This section with side shading will not appear in the final copy. - Ed. 

2730 The XSI extensions, which include the RWL extensions, are recommended to become parts of 

2731 POSIX.l _POSIX_THREADS option in the next draft. 

2732 rwl Multiple readers, single writer (read-write) locks allow many threads to have simultaneous 

2733 read-only access to data while allowing only one thread to have exclusive write access at any 

2734 given time. They are typically used to protect data that is read-only more frequently than it is 

2735 changed. 

2736 One or more readers acquire read access to the resource by performing a read lock operation on 

2737 the associated read-write lock. A writer acquires exclusive write access by performing a write 

2738 lock operation. Basically, all readers exclude any writers and a writer excludes all readers and 
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2739 any other writers. I 

2740 A thread that has blocked on a read-write lock (for example, has not yet returned from a I 

2741 pthread_nvlock_rdlock( ) or pthread_nvlock_zvrlock( ) call) shall not prevent any unblocked thread I 

2742 that is eligible to use the same processing resources from eventually making forward progress in I 

2743 its execution. Eligibility for processing resources shall be determined by the scheduling policy. I 

2744 Read-write locks can be used to synchronize threads in the current process and other processes if I 

2745 they are allocated in memory that is writable and shared among the cooperating processes and 

2746 have been initialized for this behavior. I 

2747 2.9.9 Thread Interactions with Regular File Operations I 

2748 All of the functions chmod{), close(), fchmod(), /truncate (), lseek(), open(), read{), I 

2749 readlink(), stat(), symlink(), and write{) shall be atomic with respect to each other in the effects I 

2750 specified in IEEE Std. 1003.1-200x when they operate on regular files. If two threads each call one I 

2751 of these functions, each call shall either see all of the specified effects of the other call, or none of I 

2752 them. I 
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2753 2.10 Sockets 

2754 A socket is an endpoint for communication using the facilities described in this section. A socket 

2755 is created with a specific socket type, described in Section 2.10.6 on page 82, and is associated 

2756 with a specific protocol, detailed in Section 2.10.2. A socket is accessed via a file descriptor 

2757 obtained when the socket is created. 

2758 2.10.1 Protocol Families 

2759 All network protocols are associated with a specific protocol family. A protocol family provides 

2760 basic services to the protocol implementation to allow it to function within a specific network 

2761 environment. These services may include packet fragmentation and reassembly, routing, 

2762 addressing, and basic transport. A protocol family may support multiple methods of addressing. 

2763 Each method represents an address family. A protocol family is normally comprised of a 

2764 number of protocols, one per socket type. Each protocol is characterized by an abstract socket 

2765 type. It is not required that a protocol family support all socket types. A protocol family may 

2766 contain multiple protocols supporting the same socket abstraction. 

2767 Section 2.10.17 on page 88, Section 2.10.18 on page 89, and Section 2.10.19 on page 89, 

2768 respectively, describe the use of sockets for local UNIX connections, for Internet protocols based 

2769 on IPv4, and for Internet protocols based on IPv6. 

2770 2.10.2 Protocols 

2771 A protocol supports one of the socket abstractions detailed in Section 2.10.6 on page 82. A 

2772 specific protocol may be accessed either by creating a socket of the appropriate type and 

2773 protocol family, or by requesting the protocol explicitly when creating a socket. Protocols 

2774 normally accept only one type of address format, usually determined by the addressing 

2775 structure inherent in the design of the protocol family/network architecture. Certain semantics 

2776 of the basic socket abstractions are protocol-specific. All protocols are expected to support the 

2777 basic model for their particular socket type, but may, in addition, provide non-standard facilities 

2778 or extensions to a mechanism. 

2779 2.10.3 Addressing 

2780 Associated with each protocol family is at least one address family. An address family defines 

2781 the format of a socket address. All network addresses are described using a general structure, 

2782 called a sockaddr, as defined in the System Interface Definitions volume of 

2783 IEEE Std. 1003.1-200x, <sys/socket.h>. However, each address family imposes finer and more 

2784 specific structure, generally defining a structure with fields specific to the address family. The 

2785 field sa_family in the sockaddr structure contains the address family identifier, specifying the 

2786 format of the sa_data area. The size of the sa_data area is unspecified. 

2787 2.10.4 Routing 

2788 Sockets provides packet routing facilities. A routing information database is maintained, which 

2789 is used in selecting the appropriate network interface when transmitting packets. 
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2790 2.10.5 Interfaces 

2791 Each network interface in a system corresponds to a path through which messages can be sent 

2792 and received. A network interface usually has a hardware device associated with it, though 

2793 certain interfaces such as the loopback interface, do not. 

2794 2.10.6 Socket Types 

2795 A socket is created with a specific type, which defines the communication semantics and which 

2796 allows the selection of an appropriate communication protocol. Three types are defined: 

2797 SOCK_STREAM, SOCK_SEQPACKET, and SOCK_DGRAM. Implementations may specify 

2798 additional socket types. 

2799 The SOCK_STREAM socket type provides reliable, sequenced, full-duplex octet streams 

2800 between the socket and a peer to which the socket is connected. A socket of type 

2801 SOCK_STREAM must be in a connected state before any data may be sent or received. Record 

2802 boundaries are not maintained; data sent on a stream socket using output operations of one size 

2803 may be received using input operations of smaller or larger sizes without loss of data. Data may 

2804 be buffered; successful return from an output function does not imply that the data has been 

2805 delivered to the peer or even transmitted from the local system. If data cannot be successfully 

2806 transmitted within a given time then the connection is considered broken, and subsequent 

2807 operations shall fail. A SIGPIPE signal is raised if a process sends on a broken stream (one that is 

2808 no longer connected). Support for an out-of-band data transmission facility is protocol-specific. 

2809 The SOCK_SEQPACKET socket type is similar to the SOCK_STREAM type, and is also 

2810 connection-oriented. The only difference between these types is that record boundaries are 

2811 maintained using the SOCK_SEQPACKET type. A record can be sent using one or more output 

2812 operations and received using one or more input operations, but a single operation never 

2813 transfers parts of more than one record. Record boundaries are visible to the receiver via the 

2814 MSG_EOR flag in the received message flags returned by the recvmsg{ ) function. It is protocol- 

2815 specific whether a maximum record size is imposed. 

2816 The SOCK_DGRAM socket type supports connectionless data transfer which is not necessarily 

2817 acknowledged or reliable. Datagrams may be sent to a peer named in each output operation, and 

2818 incoming datagrams may be received from multiple sources. The source address of each 

2819 datagram is available when receiving the datagram. An application may also pre-specify a peer 

2820 address, in which case calls to output functions shall send to the pre-specified peer. If a peer has 

2821 been specified, only datagrams from that peer shall be received. A datagram must be sent in a 

2822 single output operation, and must be received in a single input operation. The maximum size of 

2823 a datagram is protocol-specific; with some protocols, the limit is implementation-dependent. 

2824 Output datagrams may be buffered within the system; thus, a successful return from an output 

2825 function does not guarantee that a datagram is actually sent or received. However, 

2826 implementations should attempt to detect any errors possible before the return of an output 

2827 function, reporting any error by an unsuccessful return value. 

2828 2.10.7 Socket I/O Mode 

2829 The I/O mode of a socket is described by two file status flags. The two flags pertain to the open 

2830 file description for the socket. Both flags are initially off when a socket is created, but they may 

2831 be set and cleared by the use of the F_SETFL command of th efcntl() function. The two flags are 

2832 0_NONBLOCK and O.ASYNC. 

2833 When the 0_NONBLOCK flag is set, functions that would normally block until they are 

2834 complete either return immediately with an error, or they complete asynchronously to the 

2835 execution of the calling process. Data transfer operations (the read( ), write( ), send( ), and recv () 

2836 functions) complete immediately, transfer less than requested, and then return without blocking. 
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2837 or return an error indicating that no transfer could be made without blocking. The connect () 

2838 function initiates a connection and returns without blocking when 0_N0NBL0CK is set; it 

2839 returns the error [EINPROGRESS] to indicate that the connection was initiated successfully, but 

2840 that it has not yet completed. 

2841 The socket is in signal-driven mode when the 0_ASYNC flag is set. This mode is generally used 

2842 with 0_N0NBL0CK set. In signal-driven mode, a SIGIO signal is sent to the socket's owner 

2843 whenever an I/O operation becomes possible (when additional data could be sent, when new 

2844 data arrives to be received, or a state transition such as connection establishment or error 

2845 detection would allow a send or receive call to return status without blocking). 

2846 2.10.8 Socket Owner 

2847 The owner of a socket is unset when a socket is created. The owner may be set to a process ID or 

2848 process group ID using the F_SETOWN command of th efcntl () function. 

2849 2.10.9 Socket Queue Limits 

2850 The transmit and receive queue sizes for a socket are set when the socket is created. The default 

2851 sizes used are both protocol-specific and implementation-dependent. The sizes may be changed 

2852 using the setsockopt () function. 

2853 2.10.10 Pending Error 

2854 Errors may occur asynchronously, and be reported to the socket in response to input from the 

2855 network protocol. The socket stores the pending error to be reported to a user of the socket at the 

2856 next opportunity. The error is returned in response to a subsequent send( ), recv{ ), or getsockopt () 

2857 operation on the socket, and the pending error is then cleared. 

2858 2.10.11 Socket Receive Queue 

2859 A socket has a receive queue that buffers data when they are received by the system until they 

2860 are removed by a receive call. Depending on the type of the socket and the communication 

2861 provider, the receive queue may also contain ancillary data such as the addressing and other 

2862 protocol data associated with the normal data in the queue, and may contain out-of-band or 

2863 expedited data. The limit on the queue size includes any normal, out-of-band data, datagram 

2864 source addresses, and ancillary data in the queue. The description in this section applies to all 

2865 sockets, even though some elements cannot be present in some instances. 

2866 The contents of a receive buffer are logically structured as a series of data segments with 

2867 associated ancillary data and other information. A data segment may contain normal data or 

2868 out-of-band data, but never both. A data segment may complete a record if the protocol 

2869 supports records (always true for types SOCK_SEQPACKET and SOCK_DGRAM). A record 

2870 may be stored as more than one segment; the complete record might never be present in the 

2871 receive buffer at one time, as a portion might already have been returned to the application, and 

2872 another portion might not yet have been received from the communications provider. A data 

2873 segment may contain ancillary protocol data, which is logically associated with the segment. 

2874 Ancillary data is received as if it were queued along with the first normal data octet in the 

2875 segment (if any). A segment may contain ancillary data only, with no normal or out-of-band 

2876 data. For the purposes of this section, a datagram is considered to be a data segment that 

2877 terminates a record, and that includes a source address as a special type of ancillary data. Data 

2878 segments are placed into the queue as data is delivered to the socket by the protocol. Normal 

2879 data segments are placed at the end of the queue as they are delivered. If a new segment 

2880 contains the same type of data as the preceding segment and includes no ancillary data, and if 

2881 the preceding segment does not terminate a record, the segments are logically merged into a 
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2882 single segment. 

2883 The receive queue is logically terminated if an end-of-file indication has been received or a 

2884 connection has been terminated. A segment shall be considered to be terminated if another 

2885 segment follows it in the queue, if the segment completes a record, or if an end-of-file or other 

2886 connection termination has been reported. The last segment in the receive queue shall also be 

2887 considered to be terminated while the socket has a pending error to be reported. 

2888 A receive operation shall never return data or ancillary data from more than one segment. 

2889 2.10.12 Socket Out-of-Band Data State 

2890 The handling of received out-of-band data is protocol-specific. Out-of-band data may be placed 

2891 in the socket receive queue, either at the end of the queue or before all normal data in the queue. 

2892 In this case, out-of-band data is returned to an application program by a normal receive call. 

2893 Out-of-band data may also be queued separately rather than being placed in the socket receive 

2894 queue, in which case it shall be returned only in response to a receive call that requests out-of- 

2895 band data. It is protocol-specific whether an out-of-band data mark is placed in the receive 

2896 queue to demarcate data preceding the out-of-band data and following the out-of-band data. An 

2897 out-of-band data mark is logically an empty data segment that cannot be merged with other 

2898 segments in the queue. An out-of-band data mark is never returned in response to an input 

2899 operation. The sockatmark( ) function can be used to test whether an out-of-band data mark is the 

2900 first element in the queue. If an out-of-band data mark is the first element in the queue when an 

2901 input function is called without the MSG_PEEK option, the mark is removed from the queue and 

2902 the following data (if any) are processed as if the mark had not been present. 

2903 2.10.13 Connection Indication Queue 

2904 Sockets that are used to accept incoming connections maintain a queue of outstanding 

2905 connection indications. This queue is a list of connections that are awaiting acceptance by the 

2906 application. See listen (). 

2907 2.10.14 Signals 

2908 One category of event at the socket interface is the generation of signals. These signals report 

2909 protocol events or process errors relating to the state of the socket. The generation or delivery of 

2910 a signal does not change the state of the socket, although the generation of the signal may have 

2911 been caused by a state change. 

2912 The SIGPIPE signal shall be sent to a process that attempts to send data on a socket that is no 

2913 longer able to send. In addition, the send operation fails with the error [EPIPE]. 

2914 If a socket has an owner, the SIGURG signal is sent to the owner of the socket when it is notified 

2915 of expedited or out-of-band data. The socket state at this time is protocol-dependent, and the 

2916 status of the socket is specified in the annex for each protocol. Depending on the protocol, the 

2917 expedited data may or may not have arrived at the time of signal generation. 

2918 If a socket is in signal-driven mode and has an owner, the SIGIO signal is sent to the owner of 

2919 the socket when new data arrives at the socket, when additional data may be sent on the socket 

2920 due to a change in flow control, when a pending error is set for the socket, or when a change of 

2921 state makes further send or receive operations impossible. A signal shall be also sent when a call 

2922 to the accept () function would succeed without blocking, and when it becomes possible to write 

2923 data to a connection that was being established asynchronously. The poll () and select () functions 

2924 can be used for event management. 
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2925 2.10.15 Asynchronous Errors 

2926 If any of the following conditions occur asynchronously for a socket, the corresponding value 

2927 listed below shall become the pending error for the socket: 

2928 [ECONNABORTED] 

2929 The connection was aborted locally. 

2930 [ECONNREFUSED] 

2931 For a connection-mode socket attempting a non-blocking connection, the attempt to connect 

2932 was forcefully rejected. For a connectionless-mode socket, an attempt to deliver a datagram 

2933 was forcefully rejected. 

2934 [ECONNRESET] 

2935 The peer has aborted the connection. 

2936 [EHOSTDOWN] 

2937 The destination host has been determined to be down or disconnected. 

2938 [EHOSTUNREACH] 

2939 The destination host is not reachable. 

2940 [EMSGSIZE] 

2941 For a connectionless-mode socket, the size of a previously sent datagram prevented 

2942 delivery. 

2943 [ENETDOWN] 

2944 The local network connection is not operational. 

2945 [ENETRESET] 

2946 The connection was aborted by the network. 

2947 [ENETUNREACH] 

2948 The destination network is not reachable. 

2949 2.10.16 Use of Options 

2950 There are a number of socket options which either specialize the behavior of a socket or provide 

2951 useful information. These options may be set at different protocol levels and are always present 

2952 at the uppermost "socket" level. 

2953 Socket options are manipulated by two functions, getsockopt () and setsockopt (). These functions 

2954 allow an application program to customize the behavior and characteristics of a socket to 

2955 provide the desired effect. 

2956 All of the options have default values. The type and meaning of these values is defined by the 

2957 protocol level to which they apply. Instead of using the default values, an application program 

2958 may choose to customize one or more of the options. However, in the bulk of cases, the default 

2959 values are sufficient for the application. 

2960 Some of the options are used to enable or disable certain behavior within the protocol modules 

2961 (for example, turn on debugging) while others may be used to set protocol-specific information 

2962 (for example, IP time-to-live on all the application's outgoing packets). As each of the options is 

2963 introduced, its effect on the underlying protocol modules is described. 

2964 Table 2-4 on page 86 shows the value for the socket level. 
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2965 Table 2-4 Value of Level for Socket Options 

2966 Name Description 

2967 SOL_SOCKET Options are intended for the sockets level. 

2968 Table 2-5 lists those options present at the socket level; that is, when the level parameter of the 

2969 getsockopt () or setsockopt () function is SOL_SOCKET, the types of the option value parameters 

2970 associated with each option, and a brief synopsis of the meaning of the option value parameter. 

2971 Unless otherwise noted, each may be examined with getsockopt () and set with setsockopt () on all 

2972 types of socket. 

2973 Table 2-5 Socket-Level Options 

2974 Option Parameter Type Parameter Meaning 

2975 SO_BROADCAST (void *) int Non-zero requests permission to transmit 

2976 broadcast datagrams (SOCK_DGRAM sockets 

2977 only). 

2978 SO_DEBUG int Non-zero requests debugging in underlying 

2979 protocol modules. 

2980 SO_DONTROUTE int Non-zero requests bypass of normal routing; 

2981 route based on destination address only. 

2982 SO_ERROR int Requests and clears pending error information 

2983 on the socket (getsockopt () only). 

2984 SO_KEEPALIVE int Non-zero requests periodic transmission of 

2985 keepalive messages (protocol-specific). 

2986 SO_LINGER struct linger Specify actions to be taken for queued, unsent 

2987 data on close (): linger on/off and linger time in 

2988 seconds. 

2989 SO_OOBINLINE int Non-zero requests that out-of-band data be 

2990 placed into normal data input queue as received. 

2991 SO_RCVBUF int Size of receive buffer (mbytes). 

2992 SO_RCVLOWAT int Minimum amount of data to return to 

2993 application for input operations (in bytes). 

2994 SO_RCVTIMEO struct timeval Timeout value for a socket receive operation. 

2995 SO_REUSEADDR int Non-zero requests reuse of local addresses in 

2996 bind () (protocol-specific). 

2997 SO_SNDBUF int Size of send buffer (mbytes). 

2998 SO_SNDLOWAT int Minimum amount of data to send for output 

2999 operations (mbytes). 

3000 SO_SNDTIMEO struct timeval Timeout value for a socket send operation. 

3001 SO_TYPE int Identify socket type (getsockopt ( ) only). 

3002 The SO_BROADCAST option requests permission to send broadcast datagrams on the socket. 

3003 Support for SO_BROADCAST is protocol-specific. The default for SO_BROADCAST is that the 

3004 ability to send broadcast datagrams on a socket is disabled. 

3005 SO_DEBUG enables debugging in the underlying protocol modules. This can be useful for 

3006 tracing the behavior of the underlying protocol modules during normal system operation. The 

3007 semantics of the debug reports are implementation-dependent. The default value for 

3008 SO_DEBUG is for debugging to be turned off. 


Table 2-5 Socket-Level Options 


Option 

Parameter Type 

Parameter Meaning 

SO_BROADCAST 

(void *) int 

Non-zero requests permission to transmit 
broadcast datagrams (SOCK_DGRAM sockets 
only). 

SO_DEBUG 

int 

Non-zero requests debugging in underlying 
protocol modules. 

SO_DONTROUTE 

int 

Non-zero requests bypass of normal routing; 
route based on destination address only. 

SO_ERROR 

int 

Requests and clears pending error information 
on the socket (getsockopt () only). 

SO_KEEP ALIVE 

int 

Non-zero requests periodic transmission of 
keepalive messages (protocol-specific). 

SO_LINGER 

struct linger 

Specify actions to be taken for queued, unsent 
data on close (): linger on/off and linger time in 
seconds. 

SO_OOBINLINE 

int 

Non-zero requests that out-of-band data be 
placed into normal data input queue as received. 

SO_RCVBUF 

int 

Size of receive buffer (in bytes). 

SO_RCVLOWAT 

int 

Minimum amount of data to return to 
application for input operations (in bytes). 

SO_RCVTIMEO 

struct timeval 

Timeout value for a socket receive operation. 

SO_REUSEADDR 

int 

Non-zero requests reuse of local addresses in 
bmd() (protocol-specific). 

SO_SNDBUF 

int 

Size of send buffer (in bytes). 

SO_SNDLOWAT 

int 

Minimum amount of data to send for output 
operations (mbytes). 

SO_SNDTIMEO 

struct timeval 

Timeout value for a socket send operation. 

SO_TYPE 

int 

Identify socket type (getsockopt () only). 


Name 

Description 

SOL_SOCKET 

Options are intended for the sockets level. 
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3009 SO_DONTROUTE requests that outgoing messages bypass the standard routing facilities. The I 

3010 destination must be on a directly-connected network, and messages are directed to the I 

3011 appropriate network interface according to the destination address. It is protocol-specific I 

3012 whether this option has any effect and how the outgoing network interface is chosen. Support I 

3013 for this option with each protocol is implementation-dependent. I 

3014 SO_ERROR is used only ongetsockopt(). When this option is specified, getsockopt () returns any I 

3015 pending error on the socket and clears the error status. It returns a value of 0 if there is no I 

3016 pending error. SO_ERROR may be used to check for asynchronous errors on connected I 

3017 connectionless-mode sockets or for other types of asynchronous errors. SO_ERROR has no I 

3018 default value. I 

3019 SO_KEEPALIVE enables the periodic transmission of messages on a connected socket. The I 

3020 behavior of this option is protocol-specific. The default value for SO_KEEPALIVE is zero, I 

3021 specifying that this capability is turned off. I 

3022 The SO_LINGER option controls the action of the interface when unsent messages are queued I 

3023 on a socket and a close() is performed. The details of this option are protocol-specific. The I 

3024 default value for SO_LINGER is zero, or off, for the l_onoff element of the option value and zero I 

3025 seconds for the linger time specified by the IJinger element. I 

3026 SO_OOBINLINE is valid only on protocols that support out-of-band data. The SO_OOBINLINE I 

3027 option requests that out-of-band data be placed in the normal data input queue as received; it is I 

3028 then accessible using the read() or recv() functions without the MSG_OOB flag set. The default I 

3029 for SO_OOBINLINE is off; that is, for out-of-band data not to be placed in the normal data input I 

3030 queue. I 

3031 SO_RCVBUF requests that the buffer space allocated for receive operations on this socket be set I 

3032 to the value, in bytes, of the option value. Applications may wish to increase buffer size for high I 

3033 volume connections, or may decrease buffer size to limit the possible backlog of incoming data. I 

3034 The default value for the SO_RCVBUF option value is implementation-dependent, and may I 

3035 vary by protocol. I 

3036 The maximum value for the option for a socket may be obtained by the use of the fpathconf( ) I 

3037 function, using the value _PC_SOCK_MAXBUF. I 

3038 SO_RCVLOWAT sets the minimum number of bytes to process for socket input operations. In I 

3039 general, receive calls block until any (non-zero) amount of data is received, then return the I 

3040 smaller of the amount available or the amount requested. The default value for SO_RCVLOWAT I 

3041 is 1, and does not affect the general case. If SO_RCVLOWAT is set to a larger value, blocking I 

3042 receive calls normally wait until they have received the smaller of the low water mark value or I 

3043 the requested amount. Receive calls may still return less than the low water mark if an error I 

3044 occurs, a signal is caught, or the type of data next in the receive queue is different than that I 

3045 returned (for example, out-of-band data). As mentioned previously, the default value for I 

3046 SO_RCVLOWAT is 1 byte. It is implementation-dependent whether the SO_RCVLOWAT option I 

3047 can be set. I 

3048 SO_RCVTIMEO is an option to set a timeout value for input operations. It accepts a timeval I 

3049 structure with the number of seconds and microseconds specifying the limit on how long to wait I 

3050 for an input operation to complete. If a receive operation has blocked for this much time without I 

3051 receiving additional data, it returns with a partial count or errno set to [EWOULDBLOCK] if no I 

3052 data were received. The default for this option is the value zero, which indicates that a receive I 

3053 operation will not timeout. It is implementation-dependent whether the SO_RCVTIMEO option I 

3054 can be set. I 

3055 SO_REUSEADDR indicates that the rules used in validating addresses supplied in a bind{) I 

3056 should allow reuse of local addresses. Operation of this option is protocol-specific. The default I 
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3057 value for SO_REUSEADDR is off; that is, reuse of local addresses is not permitted. I 

3058 SO_SNDBUF requests that the buffer space allocated for send operations on this socket be set to I 

3059 the value, in bytes, of the option value. The default value for the SO_SNDBUF option value is I 

3060 implementation-dependent, and may vary by protocol. The maximum value for the option for a I 

3061 socket may be obtained by the use of the fpathconf( ) function, using the value I 

3062 _PC_SOCK_MAXBUF. I 

3063 SO_SNDLOWAT sets the minimum number of bytes to process for socket output operations. I 

3064 Most output operations process all of the data supplied by the call, delivering data to the I 

3065 protocol for transmission and blocking as necessary for flow control. Non-blocking output I 

3066 operations process as much data as permitted subject to flow control without blocking, but I 

3067 process no data if flow control does not allow the smaller of the send low water mark value or I 

3068 the entire request to be processed. A select () operation testing the ability to write to a socket I 

3069 returns true only if the send low water mark could be processed. The default value for I 

3070 SO_SNDLOWAT is implementation-dependent and protocol-specific. It is implementation- I 

3071 dependent whether the SO_SNDLOWAT option can be set. I 

3072 SO_SNDTIMEO is an option to set a timeout value for the amount of time that an output I 

3073 function shall block because flow control prevents data from being sent. As noted in Table 2-5 on I 

3074 P a g e 86, the option value is a timeval structure with the number of seconds and microseconds I 

3075 specifying the limit on how long to wait for an output operation to complete. If a send operation I 

3076 has blocked for this much time, it returns with a partial count or errno set to [EWOULDBLOCK] I 

3077 if no data were sent. The default for this option is the value zero, which indicates that a send I 

3078 operation will not timeout. It is implementation-dependent whether the SO_SNDTIMEO option I 

3079 can be set. I 

3080 SO_TYPE is used only on getsockopt {). When this option is specified, getsockopt() returns the I 

3081 type of the socket (for example, SOCK_STREAM). This option is useful to servers that inherit I 

3082 sockets on start-up. SO_TYPE has no default value. I 

3083 2.10.17 Use of Sockets for Local UNIX Connections I 

3084 Support for UNIX domain sockets is mandatory. I 

3085 UNIX domain sockets provide process-to-process communication in a single system. I 

3086 2.10.17.1 Headers I 

3087 Symbolic constant AF_UNIX is defined in the <sys/socket.h> header to identify the UNIX I 

3088 domain address family. The <sys/un.h> header contains other definitions used in connection I 

3089 with UNIX domain sockets. See the System Interface Definitions volume of I 

3090 IEEE Std. 1003.1-200x, Chapter 13, Headers. I 

3091 The sockaddr_storage structure defined in <sys/socket.h> is large enough to accommodate a I 

3092 sockaddr_un structure (see the <sys/un.h> header defined in the System Interface Definitions I 

3093 volume of IEEE Std. 1003.1-200x, Chapter 13, Headers) and is aligned at an appropriate I 

3094 boundary so that pointers to it can be cast as pointers to sockaddr_un structures and used to I 

3095 access the fields of those structures without alignment problems. When a sockaddr_storage I 

3096 structure is cast as a sockaddr_un structure, the ss_family field maps onto the sunjamily field. I 
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3097 2.10.18 Use of Sockets over Internet Protocols Based on IPv4 

3098 Support for sockets over Internet protocols based on IPv4 is mandatory. 

3099 2.10.18.1 Headers 

3100 Symbolic constant AF_INET is defined in the <sys/socket.h> header to identify the IPv4 Internet 

3101 address family. The <netinet/in.h> header contains other definitions used in connection with 

3102 IPv4 Internet sockets. See the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

3103 Chapter 13, Headers. 

3104 The sockaddr_storage structure defined in <sys/socket.h> is large enough to accommodate a 

3105 sockaddr_in structure (see the <netinet/in.h> header defined in the System Interface Definitions 

3106 volume of IEEE Std. 1003.1-200x, Chapter 13, Headers) and is aligned at an appropriate 

3107 boundary so that pointers to it can be cast as pointers to sockaddr_in structures and used to 

3108 access the fields of those structures without alignment problems. When a sockaddr_storage 

3109 structure is cast as a sockaddr_in structure, the ssjamily field maps onto the sin_family field. 

3110 2.10.19 Use of Sockets over Internet Protocols Based on IPv6 

3111 ip6 Support for sockets over Internet protocols based on IPv6 is optional. 

3112 To enable smooth transition from IPv4 to IPv6, the features defined in this section may, in certain 

3113 circumstances, also be used in connection with IPv4; see Section 2.10.19.2 on page 90. 

3114 2.10.19.1 Addressing 

3115 IPv6 overcomes the addressing limitations of previous versions by using 128-bit addresses 

3116 instead of 32-bit addresses. The IPv6 address architecture is described in RFC 2373. 

3117 

3118 

3119 

3120 

3121 

3122 

3123 

3124 

3125 

3126 

3127 

3128 

3129 

3130 

3131 

3132 

3133 

3134 

3135 

3136 

3137 A multicast address can be global, node-local, link-local, site-local, or organization-local. 


There are three kinds of IPv6 address: 

Unicast 

Identifies a single interface. 

A unicast address can be global, link-local (designed for use on a single link), or site-local 
(designed for systems not connected to the Internet). Link-local and site-local addresses 
need not be globally unique. 

Anycast 

Identifies a set of interfaces such that a packet sent to the address can be delivered to any 
member of the set. 

An anycast address is similar to a unicast address; the nodes to which an anycast address is 
assigned must be explicitly configured to know that it is an anycast address. 

Multicast 

Identifies a set of interfaces such that a packet sent to the address should be delivered to 
every member of the set. 

An application can send multicast datagrams by simply specifying an IPv6 multicast 
address in the address argument of sendto (). To receive multicast datagrams, an application 
must join the multicast group (using setsockopt () with IPV6_JOIN_GROUP) and must bind 
to the socket the UDP port on which datagrams will be received. Some applications should 
also bind the multicast group address to the socket, to prevent other datagrams destined to 
that port from being delivered to the socket. 
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3138 

3139 

3140 

3141 

3142 

3143 

3144 

3145 Two sets of IPv6 addresses are defined to correspond to IPv4 addresses: 

3146 IPv4-compatible addresses 

3147 These are assigned to nodes that support IPv6 and can be used when traffic is "tunneled” 

3148 through IPv4. 

3149 IPv4-mapped addresses 

3150 These are used to represent IPv4 addresses in IPv6 address format; see Section 2.10.19.2. 

3151 Note that the unspecified address and the loopback address must not be treated as IPv4- 

3152 compatible addresses. 

3153 2.10.19.2 Compatibility with IPv4 

3154 The API provides the ability for IPv6 applications to interoperate with applications using IPv4, 

3155 by using IPv4-mapped IPv6 addresses. These addresses can be generated automatically by the 

3156 getipnodebyname() function when the specified host has only IPv4 addresses (as described in 

3157 endhostent ()). 

3158 Applications may use AF_INET6 sockets to open TCP connections to IPv4 nodes, or send UDP 

3159 packets to IPv4 nodes, by simply encoding the destination's IPv4 address as an IPv4-mapped 

3160 IPv6 address, and passing that address, within a sockaddr_in6 structure, in the connect{), 

3161 s endto() or sendmsg () function. When applications use AF_INET6 sockets to accept TCP 

3162 connections from IPv4 nodes, or receive UDP packets from IPv4 nodes, the system returns the 

3163 peer's address to the application in the accept (), recvfrom (), recvmsg( ), or getpeername( ) function 

3164 using a sockaddr_in6 structure encoded this way. If a node has an IPv4 address, then the 

3165 implementation may allow applications to communicate using that address via an AF_INET6 

3166 socket. In such a case, the address will be represented at the API by the corresponding IPv4- 

3167 mapped IPv6 address. Also, the implementation may allow an AF_INET6 socket bound to 

3168 in6addr_any to receive inbound connections and packets destined to one of the node's IPv4 

3169 addresses. 

3170 An application may use AF_INET6 sockets to bind to a node's IPv4 address by specifying the 

3171 address as an IPv4-mapped IPv6 address in a sockaddr_in6 structure in the bind( ) function. For 

3172 an AF INET6 socket bound to a node's IPv4 address, the system returns the address in the 

3173 getsocknamei ) function as an IPv4-mapped IPv6 address in a sockaddr_in6 structure. 

3174 2.10.19.3 Interface Identification 

3175 Each local interface is assigned a unique positive integer as a numeric index. Indexes start at 1; 

3176 zero is not used. There may be gaps so that there is no current interface for a particular positive 

3177 index. Each interface also has a unique implementation-dependent name. 


The following special IPv6 addresses are defined: 

Unspecified 

An address that is not assigned to any interface and is used to indicate the absence of an 
address. 

Loopback 

A unicast address that is not assigned to any interface and can be used by a node to send 
packets to itself. 


90 


Technical Standard (2000) (Draft February 29, 2000) 





General Information 


Sockets 


3178 2.10.19.4 Options 

3179 

3180 

3181 

3182 

3183 

3184 

3185 

3186 An attempt to read this option using getsockopt () results in an [EOPNOTSUPP] error. 

3187 

3188 

3189 

3190 

3191 An attempt to read this option using getsockopt () results in an [EOPNOTSUPP] error. 

3192 The value of this option is an ipv6_mreq structure. 

3193 IP V 6_MULTIC AST_HOPS 

3194 The value of this option is the hop limit for outgoing multicast IPv6 packets sent via the 

3195 socket. Its possible values are the same as those of IPV6_UNICAST_HOPS. If the 

3196 IPV6_MULTICAST_HOPS option is not set, a value of 1 is assumed. This option can be set 

3197 via setsockopt () and read via getsockopt (). 

3198 IP V 6_MULTIC AST_IF 

3199 The index of the interface to be used for outgoing multicast packets. It can be set via 

3200 setsockopt () and read via getsockopt (). 

3201 IP V 6_MULTIC AST_LOOP 

3202 This option controls whether outgoing multicast packets should be delivered back to the 

3203 local application when the sending interface is itself a member of the destination multicast 

3204 group. If it is set to 1 they are delivered. If it is set to 0 they are not. Other values result in an 

3205 [EINVAL] error. This option can be set via setsockopt () and read via getsockopt (). 

3206 IPV6_UNICAST_HOPS 

3207 The value of this option is the hop limit for outgoing unicast IPv6 packets sent via the 

3208 socket. If the option is not set, or is set to -1, the system selects a default value. Attempts to 

3209 set a value less than -1 or greater than 255 result in an [EINVAL] error. This option can be 

3210 set via setsockopt () and read via getsockopt (). 

3211 An [EOPNOTSUPP] error results if IPV6JOIN_GROUP or IPV6_LEAVE_GROUP is used with 

3212 getsockopt (). 

3213 2.10.19.5 Headers 

3214 Symbolic constant AF_INET6 is defined in the <sys/socket.h> header to identify the IPv6 

3215 Internet address family. See the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

3216 Chapter 13, Headers. 

3217 The sockaddr_storage structure defined in <sys/socket.h> is large enough to accommodate a 

3218 sockaddr_in6 structure (see the <netinet/in.h> header defined in the System Interface 

3219 Definitions volume of IEEE Std. 1003.1-200x, Chapter 13, Headers) and is aligned at an 

3220 appropriate boundary so that pointers to it can be cast as pointers to sockaddr_in6 structures 

3221 and used to access the fields of those structures without alignment problems. When a 


The value of this option is an ipv6_mreq structure. 

IPV 6_LE AVE_GROUP 

When set via setsockopt (), it removes the application from the multicast group on an 
interface (identified by its index) and addressed by a given multicast address. 


The following options apply at the IPPROTO_IPV6 level: 

IPV6JOIN_GROUP 

When set via setsockopt (), it joins the application to a multicast group on an interface 
(identified by its index) and addressed by a given multicast address, enabling packets sent 
to that address to be read via the socket. If the interface index is specified as zero, the 
system selects the interface (for example, by looking up the address in a routing table and 
using the resulting interface). 
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3222 sockaddr_storage structure is cast as a sockaddr_in6 structure, the ss_famity field maps onto the 

3223 sin6Jamily field. 

3224 The <netinet/in.h>, <arpa/inet.h>, and <netdb.h> headers contain other definitions used in 

3225 connection with IPv6 Internet sockets; see the System Interface Definitions volume of 

3226 IEEE Std. 1003.1-200x, Chapter 13, Headers. 
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3227 2.11 Data Types 

3228 All of the data types used by various functions are defined by the implementation. The 

3229 following table describes some of these types. Other types referenced in the description of a 

3230 function, not mentioned here, can be found in the appropriate header for that function. 

3231 


3232 

Defined Type 

Description 

3233 

cc_t 

Type used for terminal special characters. 

3234 

clock_t 

Arithmetic type used for processor times, as defined in the ISO C 

3235 


standard. 

3236 

clockid_t 

Used for clock ID type in some timer functions. 

3237 

dev_t 

Arithmetic type used for device numbers. 

3238 

DIR 

Type representing a directory stream. 

3239 

div_t 

Structure type returned by the div {) function. 

3240 

FILE 

Structure containing information about a file. 

3241 

glob_t 

Structure type used in path name pattern matching. 

3242 

fpos_t 

Type containing all information needed to specify uniquely every 

3243 


position within a file. 

3244 

gid_t 

Arithmetic type used for group IDs. 

3245 

iconv_t 

Type used for conversion descriptors. 

3246 

id_t 

Arithmetic type used as a general identifier; can be used to contain 

3247 


at least the largest of a pid_t, uid_t, or gid_t. 

3248 

ino_t 

Arithmetic type used for file serial numbers. 

3249 

key_t 

Arithmetic type used for XSI interprocess communication. 

3250 

ldiv_t 

Structure type returned by the Idiv () function. 

3251 

mode_t 

Arithmetic type used for file attributes. 

3252 

mqd_t 

Used for message queue descriptors. 

3253 

nfds_t 

Integral type used for the number of file descriptors. 

3254 

nlink_t 

Arithmetic type used for link counts. 

3255 

off_t 

Signed arithmetic type used for file sizes. 

3256 

pid_t 

Signed arithmetic type used for process and process group IDs. 

3257 

posix_typed_mem_info 

Structure containing typed memory information retrieved 

3258 


in a call to posix_typed_mem_get_info (). 

3259 

pthread_attr_t 

Used to identify a thread attribute object. 

3260 

pthread_cond_t 

Used for condition variables. 

3261 

pthread_condattr_t 

Used to identify a condition attribute object. 

3262 

pthread_key_t 

Used for thread-specific data keys. 

3263 

pthread_mutex_t 

Used for mutexes. 

3264 

pthread_mutexattr_t 

Used to identify a mutex attribute object. 

3265 

pthread_once_t 

Used for dynamic package initialization. 

3266 

pthread_rwlock_t 

Used for read-write locks. 

3267 

pthread_rwlockattr_t 

Used for read-write lock attributes. 

3268 

pthread_t 

Used to identify a thread. 

3269 

ptrdiff_t 

Signed integral type of the result of subtracting two pointers. 

3270 

regex_t 

Structure type used in regular expression matching. 

3271 

regmatch_t 

Structure type used in regular expression matching. 

3272 

rlim_t 

Unsigned arithmetic type used for limit values, to which objects of 

3273 


type int and off_t can be cast without loss of value. 
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3274 


3275 

Defined Type 

Description 

3276 

sem_t 

Type used in performing semaphore operations. 

3277 

sig_atomic_t 

Integral type of an object that can be accessed as an atomic 

3278 


entity, even in the presence of asynchronous interrupts. 

3279 

sigset_t 

Integral or structure type of an object used to represent sets 

3280 


of signals. 

3281 

size_t 

Unsigned integral type used for size of objects. 

3282 

speed_t 

Type used for terminal baud rates. 

3283 

ssize_t 

Arithmetic type used for a count of bytes or an error indication. 

3284 

suseconds_t 

Signed arithmetic type used for time in microseconds. 

3285 

tcflag_t 

Type used for terminal modes. 

3286 

time_t 

Arithmetic type used for time in seconds, as defined in the ISO C 

3287 


standard. 

3288 

timer_t 

Used for timer ID returned by the timer_create () function. 

3289 

uid_t 

Arithmetic type used for user IDs. 

3290 

useconds_t 

Integral type used for time in microseconds. 

3291 

va_list 

Type used for traversing variable argument lists. 

3292 

wchar_t 

Integral type whose range of values can represent distinct codes for 

3293 


all members of the largest extended character set specified by the 

3294 


supported locales. 

3295 

wctype_t 

Scalar type which represents a character class descriptor. 

3296 

wint_t 

Integral type capable of storing any valid value of wchar_t or 

3297 


WEOF. 

3298 

wordexp_t 

Structure type used in word expansion. 


3299 
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System Interfaces 


3301 This chapter describes the functions, macros, and external variables to support applications 

3302 portability at the C-language source level. 
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3303 NAME 

3304 FD_CLR — macros for synchronous I/O multiplexing 

3305 SYNOPSIS 

3306 tinclude <sys/time.h> 

3307 FD_CLR(int fd, fd_set *fdset); 

3308 FD_ISSET (int fd, fd_set *fdset); 

3309 FD_SET (int fd, fd_set *fdset); 

3310 FD_ZERO (fd_set *fdset); 

3311 DESCRIPTION 

3312 Refer to select (). 
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3313 NAME 

3314 _exit — terminate a process 

3315 SYNOPSIS 

3316 tinclude <unistd.h> 

3317 void _exit (int status) ; 

3318 DESCRIPTION 

3319 Refer to exit (). 
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3320 NAME 

3321 _longjmp, _setjmp — non-local goto 

3322 SYNOPSIS 

3323 xsi #include <setjmp.h> 

3324 void _long jmp ( jmp_buf env, int val) ; 

3325 int _set jmp ( jmp_buf env); 

3326 

3327 DESCRIPTION 

3328 The Jongjmp () and _setjmp () functions are identical to longjmp () and setjmp (), respectively, with 

3329 the additional restriction that Jongjmp () and _setjmp () do not manipulate the signal mask. 

3330 If Jongjmp () is called even though env was never initialized by a call to _setjmp (), or when the 

3331 last such call was in a function that has since returned, the results are undefined. 

3332 RETURN VALUE 

3333 Refer to longjmp () and setjmp (). 

3334 ERRORS 

3335 No errors are defined. 

3336 EXAMPLES 

3337 None. 

3338 APPLICATION USAGE 

3339 If Jongjmp () is executed and the environment in which _setjmp () was executed no longer exists, 

3340 errors can occur. The conditions under which the environment of the _setjmp () no longer exists 

3341 include exiting the function that contains the _setjmp () call, and exiting an inner block with 

3342 temporary storage. This condition might not be detectable, in which case the Jongjmp () occurs 

3343 and, if the environment no longer exists, the contents of the temporary storage of an inner block 

3344 are unpredictable. This condition might also cause unexpected process termination. If the 

3345 function has returned, the results are undefined. 

3346 Passing longjmp () a pointer to a buffer not created by setjmp (), passing Jongjmp () a pointer to a 

3347 buffer not created by _setjmp(), passing siglongjmpO a pointer to a buffer not created by 

3348 sigsetjmp (), or passing any of these three functions a buffer that has been modified by the user 

3349 can cause all the problems listed above, and more. 

3350 The Jongjmp () and _setjmp () functions are included to support programs written to historical 

3351 system interfaces. New applications should use siglongjmpO and sigsetjmp () respectively. 

3352 RATIONALE 

3353 None. 

3354 FUTURE DIRECTIONS 

3355 None. 

3356 SEE ALSO 

3357 longjmp(), setjmp0, siglongjmpO, sigsetjmp0/ the System Interface Definitions volume of 

3358 IEEE Std. 1003.1-200x, <setjmp.h> 

3359 CHANGE HISTORY 

3360 First released in Issue 4, Version 2. 
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3361 Issue 5 

3362 Moved from X/OPEN UNIX extension to BASE. 
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3363 NAME 

3364 _setjmp — set jump point for a non-local goto 

3365 SYNOPSIS 

3366 xsi #include <setjmp.h> 

3367 int _set jmp ( jmp_buf env) ; 

3368 

3369 DESCRIPTION 

3370 Refer to Jongjmp (). 
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3371 NAME 

3372 _tolower — transliterate uppercase characters to lowercase 

3373 SYNOPSIS 

3374 xsi #include <ctype.h> 

3375 int _tolower (int c) ; 

3376 

3377 DESCRIPTION 

3378 The _toloiver() macro shall be equivalent to tolozver(c) except that the application shall ensure I 

3379 that the argument c is an uppercase letter. I 

3380 RETURN VALUE 

3381 Upon successful completion, _tolower() shall return the lowercase letter corresponding to the I 

3382 argument passed. 

3383 ERRORS 

3384 No errors are defined. 

3385 EXAMPLES 

3386 None. 

3387 APPLICATION USAGE 

3388 None. 

3389 RATIONALE 

3390 None. 

3391 FUTURE DIRECTIONS 

3392 None. 

3393 SEE ALSO 

3394 tolozver( ), isupper( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <ctype.h>, I 

3395 the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale I 

3396 CHANGE HISTORY 

3397 First released in Issue 1. 

3398 Derived from Issue 1 of the SVID. 

3399 Issue 4 

3400 The RETURN VALUE section is expanded. I 

3401 Issue 6 I 

3402 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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3403 NAME 

3404 _toupper — transliterate lowercase characters to uppercase 

3405 SYNOPSIS 

3406 xsi tinclude <ctype.h> 

3407 int _toupper (int c) ; 

3408 

3409 DESCRIPTION 

3410 The _tonpper() macro shall be equivalent to tonpper( ) except that the application shall ensure I 

3411 that the argument c is a lowercase letter. I 

3412 RETURN VALUE 

3413 Upon successful completion, _toupper() shall return the uppercase letter corresponding to the I 

3414 argument passed. 

3415 ERRORS 

3416 No errors are defined. 

3417 EXAMPLES 

3418 None. 

3419 APPLICATION USAGE 

3420 None. 

3421 RATIONALE 

3422 None. 

3423 FUTURE DIRECTIONS 

3424 None. 

3425 SEE ALSO 

3426 islower( ), tonpper( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <ctype.h>, I 

3427 the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale I 

3428 CHANGE HISTORY 

3429 First released in Issue 1. 

3430 Derived from Issue 1 of the SVID. 

3431 Issue 4 

3432 The RETURN VALUE section is expanded. I 

3433 Issue 6 I 

3434 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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3435 NAME 

3436 a641,164a — convert between a 32-bit integer and a radix-64 ASCII string 

3437 SYNOPSIS 

3438 xsi tinclude <stdlib.h> 

3439 long a641 (const char *s) ; 

3440 char *164a(long value)} 

3441 

3442 DESCRIPTION 

3443 These functions are used to maintain numbers stored in radix-64 ASCII characters. This is a 

3444 notation by which 32-bit integers can be represented by up to six characters; each character 

3445 represents a digit in radix-64 notation. If the type long contains more than 32 bits, only the low- 

3446 order 32 bits shall be used for these operations. 

3447 The characters used to represent digits are ' .' (dot) for 0, ' /' for 1, 0 through 9 for 2-11, ' A' 

3448 through ' Z' for 12-37, and ' a' through ' z' for 38-63. 

3449 The a64l () function shall take a pointer to a radix-64 representation, in which the first digit is the 

3450 least significant, and return a corresponding long value. If the string pointed to by s contains 

3451 more than six characters, a64l() shall use the first six. If the first six characters of the string 

3452 contain a null terminator, a64l() shall use only characters preceding the null terminator. The 

3453 a64l () function scans the character string from left to right with the least significant digit on the 

3454 left, decoding each character as a 6-bit radix-64 number. If the type long contains more than 32 

3455 bits, the resulting value is sign-extended. The behavior of a64l() is unspecified if s is a null 

3456 pointer or the string pointed to by s was not generated by a previous call to 164a (). 

3457 The I64a() function shall take a long argument and return a pointer to the corresponding radix- 

3458 64 representation. The behavior of 164a () is unspecified if value is negative. 

3459 The value returned by 164a () may be a pointer into a static buffer. Subsequent calls to 164a () may 

3460 overwrite the buffer. 

3461 The I64a() function need not be reentrant. A function that is not required to be reentrant is not 

3462 required to be thread-safe. 

3463 RETURN VALUE 

3464 Upon successful completion, a64l () shall return the long value resulting from conversion of the I 

3465 input string. If a string pointed to by s is an empty string, a64l () shall return 0L. 

3466 The 164a () function shall return a pointer to the radix-64 representation. If value is 0L, 164a () shall 

3467 return a pointer to an empty string. 

3468 ERRORS 

3469 No errors are defined. 

3470 EXAMPLES 

3471 None. 

3472 APPLICATION USAGE 

3473 If the type long contains more than 32 bits, the result of a64l(J64a(x)) is x in the low-order 32 bits. 

3474 RATIONALE 

3475 None. 
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3476 FUTURE DIRECTIONS 

3477 None. 

3478 SEE ALSO 

3479 strtoul(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

3480 CHANGE HISTORY 

3481 First released in Issue 4, Version 2. 

3482 Issue 5 

3483 Moved from X/OPEN UNIX extension to BASE. 

3484 Normative text previously in the APPLICATION USAGE section moved to the DESCRIPTION. 

3485 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 
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3486 NAME 

3487 abort — generate an abnormal process abort 

3488 SYNOPSIS 

3489 tinclude <stdlib.h> 

3490 void abort (void) ; 

3491 DESCRIPTION 

3492 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

3493 conflict between the requirements described here and the ISO C standard is unintentional. This I 

3494 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

3495 The abort () function shall cause abnormal process termination to occur, unless the signal 

3496 SIGABRT is being caught and the signal handler does not return. 

3497 cx The abnormal termination processing shall include at least the effect of /close () on all open 

3498 streams and the default actions defined for SIGABRT. 

3499 xsi On XSI-conformant systems, the abnormal termination processing shall include at least the 

3500 effect of /close () on all open streams, and message catalog descriptors, and the default actions 

3501 defined for SIGABRT. 

3502 The SIGABRT signal shall be sent to the calling process as if by means of raise() with the 

3503 argument SIGABRT. 

3504 cx The status made available to ivait( ) or zvaitpid () by abort () shall be that of a process terminated 

3505 by the SIGABRT signal. The abort () function shall override blocking or ignoring the SIGABRT 

3506 signal. 

3507 RETURN VALUE 

3508 The abort () function shall not return. 

3509 ERRORS 

3510 No errors are defined. 

3511 EXAMPLES 

3512 None. 

3513 APPLICATION USAGE 

3514 Catching the signal is intended to provide the application writer with a portable means to abort 

3515 processing, free from possible interference from any implementation-dependent library 

3516 functions. If SIGABRT is neither caught nor ignored, and the current directory is writable, a core 

3517 dump may be produced. 

3518 RATIONALE 

3519 None. 

3520 FUTURE DIRECTIONS 

3521 None. 

3522 SEE ALSO 

3523 exit(), raise(), signal (), zvait(), zvaitpid {), the System Interface Definitions volume of 

3524 IEEE Std. 1003.1-200x, <stdlib.h> 

3525 CHANGE HISTORY 

3526 First released in Issue 1. 

3527 Derived from Issue 1 of the SVID. 
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3528 Issue 4 

3529 The following changes are incorporated in this issue for alignment with the ISO C standard and 

3530 the ISO POSIX-1 standard: 

3531 • The argument list is explicitly defined as void. 

3532 • The DESCRIPTION is revised to identify the correct order in which operations occur. It also 

3533 identifies: 


3534 — How the calling process is signaled 

3535 — How status information is made available to the host environment 


3536 — That abort () overrides blocking or ignoring of the SIGABRT signal 

3537 • The APPLICATION USAGE section is replaced. 

3538 Issue 6 

3539 Extensions beyond the ISO C standard are now marked. 
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3540 NAME 

3541 abs — return an integer absolute value 

3542 SYNOPSIS 

3543 #include <stdlib.h> 

3544 int abs (int i) ; 

3545 DESCRIPTION 

3546 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

3547 conflict between the requirements described here and the ISO C standard is unintentional. This I 

3548 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

3549 The abs( ) function shall compute the absolute value of its integer operand, i. If the result cannot 

3550 be represented, the behavior is undefined. 

3551 RETURN VALUE 

3552 The abs( ) function shall return the absolute value of its integer operand. 

3553 ERRORS 

3554 No errors are defined. 

3555 EXAMPLES 

3556 None. 

3557 APPLICATION USAGE 

3558 In two's-complement representation, the absolute value of the negative integer with largest 

3559 magnitude |INT_MIN} might not be representable. 

3560 RATIONALE 

3561 None. 

3562 FUTURE DIRECTIONS 

3563 None. 

3564 SEE ALSO 

3565 fabs (), labs (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

3566 CHANGE HISTORY 

3567 First released in Issue 1. 

3568 Derived from Issue 1 of the SVID. 

3569 Issue 4 

3570 In the APPLICATION USAGE section, the phrase "{INT_MIN} is undefined" is replaced with 

3571 "|INT_MIN} might not be representable". 

3572 Issue 6 I 

3573 Extensions beyond the ISO C standard are now marked. 
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3574 NAME 

3575 accept — accept a new connection on a socket 

3576 SYNOPSIS 

3577 #include <sys/socket.h> 


3578 int accept (int socket, struct sockaddr * address, 

3579 socklen_t *address_len) ; 


3580 DESCRIPTION 

3581 The accept () function shall extract the first connection on the queue of pending connections, 

3582 create a new socket with the same socket type protocol and address family as the specified 

3583 socket, and allocate a new file descriptor for that socket. 

3584 The accept () function takes the following arguments: 


3585 

3586 

3587 

3588 


socket 


address 


Specifies a socket that was created with socket (), has been bound to an address 
with bind (), and has issued a successful call to listen (). 

Either a null pointer, or a pointer to a sockaddr structure where the address of 
the connecting socket shall be returned. 


3589 address_len Points to a socklen_t structure which on input specifies the length of the 

3590 supplied sockaddr structure, and on output specifies the length of the stored 

3591 address. 


3592 If address is not a null pointer, the address of the peer for the accepted connection shall be stored 

3593 in the sockaddr structure pointed to by address, and the length of this address shall be stored in 

3594 the object pointed to by addressjen. 

3595 If the actual length of the address is greater than the length of the supplied sockaddr structure, 

3596 the stored address shall be truncated. 


3597 If the protocol permits connections by unbound clients, and the peer is not bound, then the value 

3598 stored in the object pointed to by address is unspecified. 

3599 If the listen queue is empty of connection requests and 0_N0NBL0CK is not set on the file 

3600 descriptor for the socket, accept () shall block until a connection is present. If the listen () queue is 

3601 empty of connection requests and 0_NONBLOCK is set on the file descriptor for the socket, 

3602 accept( ) shall fail and set errno to [EAGAIN] or [EWOULDBLOCK]. 

3603 The accepted socket cannot itself accept more connections. The original socket remains open and 

3604 can accept more connections. 

3605 RETURN VALUE 

3606 Upon successful completion, accept () shall return the non-negative file descriptor of the accepted 

3607 socket. Otherwise, -1 shall be returned and errno set to indicate the error. 

3608 ERRORS 

3609 The accept () function shall fail if: 

3610 [EAGAIN] or [EWOULDBLOCK] 

3611 0_NONBLOCK is set for the socket file descriptor and no connections are 

3612 present to be accepted. 

3613 [EBADF] The socket argument is not a valid file descriptor. 

3614 [ECONNABORTED] 

3615 A connection has been aborted. 
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3616 [EFAULT] The address or address_len parameter cannot be accessed or written. 

3617 [EINTR] The accept () function was interrupted by a signal that was caught before a 

3618 valid connection arrived. 

3619 [EINVAL] The socket is not accepting connections. 

3620 [EMFILE] {OPEN_MAX[ file descriptors are currently open in the calling process. 

3621 [ENFILE] The maximum number of file descriptors in the system are already open. 

3622 [ENOTSOCK] The socket argument does not refer to a socket. 

3623 [EOPNOTSUPP] The socket type of the specified socket does not support accepting 

3624 connections. 

3625 The accept () function may fail if: 

3626 [ENOBUFS] No buffer space is available. 

3627 [ENOMEM] There was insufficient memory available to complete the operation. 

3628 xsr [ENOSR] There were insufficient STREAMS resources available to complete the 

3629 operation. 

3630 xsr [EPROTO] A protocol error has occurred; for example, the STREAMS protocol stack has 

3631 not been initialized. 

3632 EXAMPLES 

3633 None. 

3634 APPLICATION USAGE 

3635 When a connection is available, select () indicates that the file descriptor for the socket is ready 

3636 for reading. 

3637 RATIONALE 

3638 None. 

3639 FUTURE DIRECTIONS 

3640 None. 

3641 SEE ALSO 

3642 bind(), connect(), listen(), socket (), the System Interface Definitions volume of 

3643 IEEE Std. 1003.1-200x, <sys/socket.h> 

3644 CHANGE HISTORY 

3645 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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3646 NAME 

3647 access — determine accessibility of a file 

3648 SYNOPSIS 

3649 #include <unistd.h> 


3650 int access (const char *path, int amode) ; 

3651 DESCRIPTION 

3652 The access () function shall check the file named by the path name pointed to by the path 

3653 argument for accessibility according to the bit pattern contained in amode, using the real user ID 

3654 in place of the effective user ID and the real group ID in place of the effective group ID. 

3655 The value of amode is either the bitwise-inclusive OR of the access permissions to be checked 

3656 (R_OK, W_OK, X_OK) or the existence test (F_OK). 

3657 If any access permissions are checked, each shall be checked individually, as described in the I 

3658 System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 3, Definitions. If the 

3659 process has appropriate privileges, an implementation may indicate success for X_OK even if 

3660 none of the execute file permission bits are set. 

3661 RETURN VALUE 

3662 If the requested access is permitted, access () succeeds and shall return 0; otherwise, -1 shall be 

3663 returned and errno shall be set to indicate the error. 


3664 ERRORS 

3665 The access () function shall fail if: 


3666 [EACCES] Permission bits of the file mode do not permit the requested access, or search 

3667 permission is denied on a component of the path prefix. 


3668 Notes to Reviewers 

3669 This section with side shading will not appear in the final copy. - Ed. 


3670 


Do the [ELOOP] errors need reconciling? 


3671 MAN [ELOOP] 

3672 


A loop exists in symbolic links encountered during resolution of the path 
argument. 


3673 

3674 

3675 

3676 


[ENAMETOOLONG] 

The length of the path argument exceeds {PATH_MAX} or a path name 
component is longer than {NAME_MAX} while _POSIX_NO_TRUNC is in 
effect. 


3677 

3678 

3679 

3680 

3681 

3682 

3683 

3684 MAN 

3685 

3686 


[ENOENT] A component of path does not name an existing file or path is an empty string. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EROFS] Write access is requested for a file on a read-only file system. 

The access () function may fail if: 

[EINVAL] The value of the amode argument is invalid. I 

[ELOOP] More than [SYMLOOP_MAX[ symbolic links were encountered during I 

resolution of the path argument. I 

[ENAMETOOLONG] 

As a result of encountering a symbolic link in resolution of the path argument, I 
the length of the substituted path name string exceeded ]PATH_MAX[. I 
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3687 man [ETXTBSY] Write access is requested for a pure procedure (shared text) file that is being 

3688 executed. 

3689 EXAMPLES 

3690 Testing for the Existence of a File 

3691 The following example tests whether a file named myfile exists in the /tmp directory. 

3692 #include <unistd.h> 

3693 

3694 int result; 

3695 char *filename = "/tmp/myfile"; 

3696 result = access (filename, F_OK) ; 

3697 APPLICATION USAGE 

3698 Additional values of amode other than the set defined in the description may be valid; for 

3699 example, if a system has extended access controls. 

3700 RATIONALE 

3701 In early proposals, some inadequacies in the access () function led to the creation of an eaccess () 

3702 function because: 

3703 1. Historical implementations of access () do not test file access correctly when the process' 

3704 real user ID is superuser. In particular, they always return zero when testing execute 

3705 permissions without regard to whether the file is executable. 

3706 2. The superuser has complete access to all files on a system. As a consequence, programs 

3707 started by the superuser and switched to the effective user ID with lesser privileges cannot 

3708 use access () to test their file access permissions. 

3709 However, the historical model of eaccess() does not resolve problem (1), so this volume of 

3710 IEEE Std. 1003.l-200x now allows access () to behave in the desired way because several 

3711 implementations have corrected the problem. It was also argued that problem (2) is more easily 

3712 solved by using open(), chdir( ), or one of the exec functions as appropriate and responding to the 

3713 error, rather than creating a new function that would not be as reliable. Therefore, eaccess () was 

3714 taken back out of this volume of IEEE Std. 1003.1-200x. 

3715 The sentence concerning appropriate privileges and execute permission bits reflects the two 

3716 possibilities implemented by historical implementations when checking superuser access for 

3717 X_OK. 

3718 FUTURE DIRECTIONS 

3719 None. 

3720 SEE ALSO 

3721 chmod{), stat( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

3722 CHANGE HISTORY 

3723 First released in Issue 1. 

3724 Derived from Issue 1 of the SVID. 

3725 Issue 4 

3726 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

3727 • The type of argument path is changed from char* to const char*. 

3728 The following change is incorporated for alignment with the FIPS requirements: 
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3729 • In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 

3730 name component is larger that |NAME_MAX[ is now defined as mandatory and marked as 

3731 an extension. 

3732 Issue 4, Version 2 

3733 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 

3734 • It states that [ELOOP] is returned if too many symbolic links are encountered during path 

3735 name resolution. 

3736 • A second [ENAMETOOLONG] condition is defined that may report excessive length of an 

3737 intermediate result of path name resolution of a symbolic link. 

3738 Issue 6 

3739 The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

3740 • The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 

3741 This is since behavior may vary from one file system to another. 

3742 The following new requirements on POSIX implementations derive from alignment with the 

3743 Single UNIX Specification: 

3744 • The [ELOOP] mandatory error condition is added. 

3745 • A second [ENAMETOOLONG] is added as an optional error condition. 

3746 • The [ETXTBSY] optional error condition is added. 

3747 The following changes were made to align with the IEEE P1003.1a draft standard: 

3748 • The [ELOOP] optional error condition is added. 
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3749 NAME 

3750 acos — arc cosine function 

3751 SYNOPSIS 

3752 #include <math.h> 

3753 double acos (double x) ; 

3754 DESCRIPTION 

3755 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

3756 conflict between the requirements described here and the ISO C standard is unintentional. This I 

3757 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

3758 The acos() function shall compute the principal value of the arc cosine of x. The value of x 

3759 should be in the range [-1,1]. 

3760 An application wishing to check for error situations should set errno to 0 before calling acos(). If 

3761 errno is non-zero on return, or the value NaN is returned, an error has occurred. 

3762 RETURN VALUE 

3763 Upon successful completion, acos() shall return the arc cosine of x, in the range [0,7t] radians. If 

3764 xsi the value of x is not in the range [-1,1], and is not ±Inf or NaN, either 0.0 or NaN shall be 

3765 returnedand errno shall be set to [EDOM]. 

3766 xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM], If x is ±Inf, either 0.0 shall be 

3767 returned and errno shall be set to [EDOM], or NaN shall be returned and errno may be set to 

3768 [EDOM]. 

3769 ERRORS 

3770 The acos () function shall fail if: 

3771 xsi [EDOM] The value x is not ±Inf or NaN andis not in the range [—1,1]. 

3772 The acos () function may fail if: 

3773 xsi [EDOM] The value x is ±Inf or NaN. 

3774 xsi No other errors shall occur. 

3775 EXAMPLES 

3776 None. 

3777 APPLICATION USAGE 

3778 None. 

3779 RATIONALE 

3780 None. 

3781 FUTURE DIRECTIONS 

3782 None. 

3783 SEE ALSO 

3784 cos (), isnan (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

3785 CHANGE HISTORY 

3786 First released in Issue 1. 

3787 Derived from Issue 1 of the SVID. 
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3788 Issue 4 

3789 Removed references to matherr (). 

3790 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

3791 ISO C standard and to rationalize error handling in the mathematics functions. 

3792 The return value specified for [EDOM] is marked as an extension. 

3793 Issue 5 

3794 The DESCRIPTION is updated to indicate how an application should check for an error. This 

3795 text was previously published in the APPLICATION USAGE section. 
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3796 NAME 

3797 acosh, asinh, atanh — inverse hyperbolic functions 

3798 SYNOPSIS 

3799 xsi #include <math.h> 


3800 

double 

acosh(double 

x ); 

3801 

double 

asinh(double 

x ); 

3802 

double 

atanh(double 

x) } 


3803 

3804 DESCRIPTION 

3805 The acosh (), asinh (), and atanh () functions shall compute the inverse hyperbolic cosine, sine, and 

3806 tangent of their argument, respectively. 

3807 RETURN VALUE 

3808 The acosh (), asinh (), and atanh () functions shall return the inverse hyperbolic cosine, sine, and 

3809 tangent of their argument, respectively. 

3810 The acosh () function shall return an implementation-dependent value (NaN or equivalent if 

3811 available) and set errno to [EDOM] when its argument is less than 1.0. 

3812 The atanh () function shall return an implementation-dependent value (NaN or equivalent if 

3813 available) and set errno to [EDOM] when its argument has absolute value greater than 1.0. 

3814 If x is NaN, the asinh (), acosh (), and atanh () functions shall return NaN and may set errno to 

3815 [EDOM], 

3816 ERRORS 

3817 The acosh () function shall fail if: 

3818 [EDOM] The x argument is less than 1.0. 

3819 The atanh () function shall fail if: 

3820 [EDOM] The x argument has an absolute value greater than 1.0. 

3821 The atanh () function shall fail if: 

3822 [ERANGE] The x argument has an absolute value equal to 1.0 

3823 The asinh (), acosh (), and atanh () functions may fail if: 

3824 [EDOM] The value of x is NaN. 

3825 EXAMPLES 

3826 None. 

3827 APPLICATION USAGE 

3828 None. 

3829 RATIONALE 

3830 None. 

3831 FUTURE DIRECTIONS 

3832 None. 

3833 SEE ALSO 

3834 cosh(), sinh (), tanh(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

3835 <math.h> 
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3836 CHANGE HISTORY 

3837 First released in Issue 4, Version 2. 

3838 Issue 5 

3839 Moved from X/OPEN UNIX extension to BASE. 
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3840 NAME 

3841 aio_cancel — cancel an asynchronous I/O request (REALTIME) 

3842 SYNOPSIS 

3843 AIO #include <aio.h> 

3844 int aio_cancel (int fildes, struct aiocb * aiocbp) ; 

3845 

3846 DESCRIPTION 

3847 The aio_ccmcel() function shall attempt to cancel one or more asynchronous I/O requests 

3848 currently outstanding against file descriptor fildes. The aiocbp argument points to the 

3849 asynchronous I/O control block for a particular request to be canceled. If aiocbp is NULL, then 

3850 all outstanding cancelable asynchronous I/O requests against fildes shall be canceled. 

3851 Normal asynchronous notification shall occur for asynchronous I/O operations that are 

3852 successfully canceled. If there are requests that cannot be canceled, then the normal 

3853 asynchronous completion process shall take place for those requests when they are completed. 

3854 For requested operations that are successfully canceled, the associated error status shall be set to 

3855 [ECANCELED] and the return status shall be -1. For requested operations that are not 

3856 successfully canceled, the aiocbp shall not be modified by aio_cancel (). 

3857 If aiocbp is not NULL, then it fildes does not have the same value as the file descriptor with which 

3858 the asynchronous operation was initiated, unspecified results occur. 

3859 Which operations are cancelable is implementation-dependent. 

3860 RETURN VALUE 

3861 The aio_cancel () function shall return the value AIO_CANCELED to the calling process if the 

3862 requested operation(s) were canceled. The value AIO_NOTCANCELED shall be returned if at 

3863 least one of the requested operation(s) cannot be canceled because it is in progress. In this case, 

3864 the state of the other operations, if any, referenced in the call to aio_cancel () is not indicated by 

3865 the return value of aio_cancel(). The application may determine the state of affairs for these 

3866 operations by using aio_error(). The value AIO_ALLDONE is returned if all of the operations 

3867 have already completed. Otherwise, the function shall return -1 and set errno to indicate the 

3868 error. 

3869 ERRORS 

3870 The aio_cancel () function shall fail if: 

3871 [EBADF] The fildes argument is not a valid file descriptor. 

3872 EXAMPLES 

3873 None. 

3874 APPLICATION USAGE 

3875 The aio_cancel () function is part of the _POSIX_ASYNCHRONOUS_IO option and need not be 

3876 available on all implementations. 

3877 RATIONALE 

3878 None. 

3879 FUTURE DIRECTIONS 

3880 None. 
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3881 SEE ALSO 

3882 aio_read (), aio_write (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <aio.h> 

3883 CHANGE HISTORY 

3884 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

3885 Issue 6 

3886 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

3887 implementation does not support the _POSIX_ASYNCHRONOUS_IO option. 

3888 The APPLICATION USAGE section is added. 
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3889 NAME 

3890 aio_error — retrieve errors status for an asynchronous I/O operation (REALTIME) 

3891 SYNOPSIS 

3892 AIO #include <aio.h> 

3893 int aio_error(const struct aiocb * aiocbp)-, 

3894 

3895 DESCRIPTION 

3896 The aio_error() function shall return the error status associated with the aiocb structure 

3897 referenced by the aiocbp argument. The error status for an asynchronous I/O operation is the 

3898 sio errno value that would be set by the corresponding read(), ivrite(), fdatasync(), or fsync() 

3899 operation. If the operation has not yet completed, then the error status shall be equal to 

3900 [EINPROGRESS]. 

3901 RETURN VALUE 

3902 If the asynchronous I/O operation has completed successfully, then 0 shall be returned. If the 

3903 asynchronous operation has completed unsuccessfully, then the error status, as described for 

3904 sio read (), write{ ),fdatasync( ),and fsync( ), shall be returned. If the asynchronous I/O operation has 

3905 not yet completed, then [EINPROGRESS] shall be returned. 

3906 ERRORS 

3907 The aio_error( ) function may fail if: 

3908 [EINVAL] The aiocbp argument does not refer to an asynchronous operation whose 

3909 return status has not yet been retrieved. 

3910 EXAMPLES 

3911 None. 

3912 APPLICATION USAGE 

3913 The aio_error{) function is part of the _POSIX_ASYNCHRONOUS_IO option and need not be 

3914 available on all implementations. 

3915 RATIONALE 

3916 None. 

3917 FUTURE DIRECTIONS 

3918 None. 

3919 SEE ALSO 

3920 aio_cancel (), aioJsync{), aio_read (), aio_return (), aio_write( ), close ( ), exec, _exit(),fork (), 

3921 lio_listio (), lseek (), read (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

3922 <aio.h> 

3923 CHANGE HISTORY 

3924 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

3925 Issue 6 

3926 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

3927 implementation does not support the _POSIX_ASYNCHRONOUS_IO option. 

3928 The APPLICATION USAGE section is added. 
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3929 NAME 

3930 aio_fsync — asynchronous file synchronization (REALTIME) 

3931 SYNOPSIS 

3932 AIO #include <aio.h> 

3933 int aio_fsync (int op, struct aiocb *aiocbp); 

3934 

3935 DESCRIPTION 

3936 The aioJsync() function asynchronously forces all I/O operations associated with the file 

3937 indicated by the file descriptor aiojildes member of the aiocb structure referenced by the aiocbp 

3938 argument and queued at the time of the call to aioJsync{ ) to the synchronized I/O completion 

3939 state. The function call shall return when the synchronization request has been initiated or 

3940 queued to the file or device (even when the data cannot be synchronized immediately). 

3941 If op is 0_DSYNC, all currently queued I/O operations shall be completed as if by a call to 

3942 fdatasync() ; that is, as defined for synchronized I/O data integrity completion. If op is 0_SYNC, 

3943 all currently queued I/O operations shall be completed as if by a call to fsync(); that is, as 

3944 defined for synchronized I/O file integrity completion. If the aioJsync{) function fails, or if the 

3945 operation queued by aioJsync{) fails, then, as for fsync () and fdatasync (), outstanding I/O 

3946 operations are not guaranteed to have been completed. 

3947 If aioJsync{) succeeds, then it is only the I/O that was queued at the time of the call to 

3948 aio^sync () that is guaranteed to be forced to the relevant completion state. The completion of 

3949 subsequent I/O on the file descriptor is not guaranteed to be completed in a synchronized 

3950 fashion. 

3951 The aiocbp argument refers to an asynchronous I/O control block. The aiocbp value may be used 

3952 as an argument to aio_error( ) and aiojreturn () in order to determine the error status and return 

3953 status, respectively, of the asynchronous operation while it is proceeding. When the request is 

3954 queued, the error status for the operation is [EINPROGRESS]. When all data has been 

3955 successfully transferred, the error status shall be reset to reflect the success or failure of the 

3956 operation. If the operation does not complete successfully, the error status for the operation shall 

3957 be set to indicate the error. The aio_sigevent member determines the asynchronous notification to 

3958 occur as specified in Section 2.4.1 on page 43 when all operations have achieved synchronized 

3959 I/O completion. All other members of the structure referenced by aiocbp are ignored. If the 

3960 control block referenced by aiocbp becomes an illegal address prior to asynchronous I/O 

3961 completion, then the behavior is undefined. 

3962 If the aiojsync () function fails or the aiocbp indicates an error condition, data is not guaranteed 

3963 to have been successfully transferred. 

3964 RETURN VALUE 

3965 The aioJsync{ ) function shall return the value 0 to the calling process if the I/O operation is 

3966 successfully queued; otherwise, the function shall return the value -1 and set errno to indicate 

3967 the error. 


3968 ERRORS 

3969 The aiojsync () function shall fail if: 

3970 [EAGAIN] The requested asynchronous operation was not queued due to temporary 

3971 resource limitations. 


3972 [EBADF] The aiojildes member of the aiocb structure referenced by the aiocbp argument 

3973 is not a valid file descriptor open for writing. 
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3974 [EINVAL] This implementation does not support synchronized I/O for this file. 

3975 [EINVAL] A value of op other than 0_DSYNC or 0_SYNC was specified. 

3976 In the event that any of the queued I/O operations fail, aioJsync{) shall return the error 

3977 condition defined for read() and write (). The error is returned in the error status for the 

3978 asynchronous fsync( ) operation, which can be retrieved using aio_error( ). 

3979 EXAMPLES 

3980 None. 

3981 APPLICATION USAGE 

3982 The ciio_fsync () function is part of the _POSIX_ASYNCHRONOUS_IO option and need not be 

3983 available on all implementations. 

3984 RATIONALE 

3985 None. 

3986 FUTURE DIRECTIONS 

3987 None. 

3988 SEE ALSO 

3989 fcntl(), fdatasync(), fsync(), open(), read(), write(), the System Interface Definitions volume of 

3990 IEEE Std. 1003.1-200x, <aio.h> 

3991 CHANGE HISTORY 

3992 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

3993 Issue 6 

3994 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

3995 implementation does not support the _POSIX_ASYNCHRONOUS_IO option. 

3996 The APPLICATION USAGE section is added. 
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3997 NAME 

3998 aio_read — asynchronous read from a file (REALTIME) 

3999 SYNOPSIS 

4000 AIO #include <aio.h> 

4001 int aio_read ( struct aiocb *aiocbp); 

4002 

4003 DESCRIPTION 

4004 The aio_read() function allows the calling process to read aiocbp-^aio_nbytes from the file 

4005 associated with aiocbp-^aioffildes into the buffer pointed to by aiocbp-^aiojmf. The function call 

4006 shall return when the read request has been initiated or queued to the file or device (even when 

4007 the data cannot be delivered immediately). 

4008 pio If prioritized I/O is supported for this file, then the asynchronous operation is submitted at a 

4009 priority equal to the scheduling priority of the process minus aiocbp-^aio_reqprio. 

4010 The aiocbp value may be used as an argument to aio_error() and aio_return() in order to 

4011 determine the error status and return status, respectively, of the asynchronous operation while it 

4012 is proceeding. If an error condition is encountered during queuing, the function call shall return 

4013 without having initiated or queued the request. The requested operation takes place at the 

4014 absolute position in the file as given by aio_offset , as if lseek ( ) were called immediately prior to 

4015 the operation with an offset equal to aiojoffset and a whence equal to ]SEEK_SET[. After a 

4016 successful call to enqueue an asynchronous I/O operation, the value of the file offset for the file 

4017 is unspecified. 

4018 The aiocbp-^aio_lio_opcode field shall be ignored by aio_read (). 

4019 The aiocbp argument points to an aiocb structure. If the buffer pointed to by aiocbp-^aio_bnf or 

4020 the control block pointed to by aiocbp becomes an illegal address prior to asynchronous I/O 

4021 completion, then the behavior is undefined. 

4022 Simultaneous asynchronous operations using the same aiocbp produce undefined results. 

4023 sio If synchronized I/O is enabled on the file associated with aiocbp-^aioffildes, the behavior of this 

4024 function shall be according to the definitions of synchronized I/O data integrity completion and 

4025 synchronized I/O file integrity completion. 

4026 For any system action that changes the process memory space while an asynchronous I/O is 

4027 outstanding to the address range being changed, the result of that action is undefined. 

4028 man For regular files, no data transfer shall occur past the offset maximum established in the open 

4029 file description associated with aiocbp-taioffildes . 

4030 RETURN VALUE 

4031 The aio_read() function shall return the value zero to the calling process if the I/O operation is 

4032 successfully queued; otherwise, the function shall return the value -1 and set errno to indicate 

4033 the error. 

4034 ERRORS 

4035 The aio_read () function shall fail if: 

4036 [E AG AIN] The requested asynchronous I/O operation was not queued due to system 

4037 resource limitations. 

4038 Each of the following conditions may be detected synchronously at the time of the call to 

4039 aio_read(), or asynchronously. If any of the conditions below are detected synchronously, the 

4040 aio_read() function shall return -1 and set errno to the corresponding value. If any of the 

4041 conditions below are detected asynchronously, the return status of the asynchronous operation 
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4042 


is set to —1, and the error status of the asynchronous operation is set to the corresponding value. 


4043 

4044 

4045 

4046 


[EBADF] The aiocbp^aiojildes argument is not a valid file descriptor open for reading. 

[EINVAL] The file offset value implied by aiocbp—^aiojjffset would be invalid, 

aiocbp—>aio_reqprio is not a valid value, or aiocbp-^aio_nbytes is an invalid 
value. 


4047 

4048 

4049 

4050 

4051 


In the case that the aio_read() successfully queues the I/O operation but the operation is 
subsequently canceled or encounters an error, the return status of the asynchronous operation is 
one of the values normally returned by the read() function call. In addition, the error status of 
the asynchronous operation is set to one of the error statuses normally set by the read () function 
call, or one of the following values: 


4052 

4053 

4054 

4055 


[EBADF] 

[ECANCELED] 

[EINVAL] 


The aiocbp-^aiojildes argument is not a valid file descriptor open for reading. 

The requested I/O was canceled before the I/O completed due to an explicit 
aio_cancel () request. 

The file offset value implied by aiocbp-^aio_offset would be invalid. 


4056 The following condition may be detected synchronously or asynchronously: 

4057 MAN 

4058 

4059 

4060 EXAMPLES 

4061 None. 

4062 APPLICATION USAGE 

4063 The aio_read () function is part of the _POSIX_ASYNCHRONOUS_IO option and need not be 

4064 available on all implementations. 

4065 RATIONALE 

4066 None. 

4067 FUTURE DIRECTIONS 

4068 None. 

4069 SEE ALSO 

4070 aio_cancel ( ), aio_error( ), liojistio (), aio_retnrn (), aio_write( ), close( ), _exit( ), exec, fork( ), lseek( ), 

4071 read( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <aio.h> 

4072 CHANGE HISTORY 

4073 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

4074 Large File Summit extensions are added. 

4075 Issue 6 

4076 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

4077 implementation does not support the _POSIX_ASYNCHRONOUS_IO option. 

4078 The APPLICATION USAGE section is added. 

4079 The following new requirements on POSIX implementations derive from alignment with the 

4080 Single UNIX Specification: 

4081 • In the DESCRIPTION, text is added to indicate setting of the offset maximum in the open file 

4082 description. This change is to support large files. 


[EOVERFLOW] The file is a regular file, aiobcp —>aio_n bytes is greater than 0, and the starting 
offset in aiobcp-^aio_offset is before the end-of-file and is at or beyond the 
offset maximum in the open file description associated with aiocbp^aio_fildes. 
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4084 


• In the ERRORS section, the [EOVERFLOW] condition is added. This change is to support 
large files. 
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4085 NAME 

4086 aio_return — retrieve return status of an asynchronous I/O operation (REALTIME) 

4087 SYNOPSIS 

4088 AIO #include <aio.h> 

4089 ssize_t aio_return (struct aiocb * aiocbp) ; 

4090 

4091 DESCRIPTION 

4092 The aio_return() function shall return the return status associated with the aiocb structure 

4093 referenced by the aiocbp argument. The return status for an asynchronous I/O operation is the 

4094 value that would be returned by the corresponding read( ), write( ), or fsync {) function call. If the 

4095 error status for the operation is equal to [EINPROGRESS], then the return status for the 

4096 operation is undefined. The aio_return( ) function may be called exactly once to retrieve the 

4097 return status of a given asynchronous operation; thereafter, if the same aiocb structure is used in 

4098 a call to aio_retnrn () or aio_error( ), an error may be returned. When the aiocb structure referred 

4099 to by aiocbp is used to submit another asynchronous operation, then aio_rehirn() may be 

4100 successfully used to retrieve the return status of that operation. 

4101 RETURN VALUE 

4102 If the asynchronous I/O operation has completed, then the return status, as described for read (), 

4103 zvrite( ), and fsync( ), shall be returned. If the asynchronous I/O operation has not yet completed, 

4104 the results of aio_return () are undefined. 

4105 ERRORS 

4106 The aio_retnrn () function may fail if: 

4107 [EINVAL] The aiocbp argument does not refer to an asynchronous operation whose 

4108 return status has not yet been retrieved. 

4109 EXAMPLES 

4110 None. 

4111 APPLICATION USAGE 

4112 The aio_retnrn() function is part of the _POSIX_ASYNCHRONOUS_IO option and need not be 

4113 available on all implementations. 

4114 RATIONALE 

4115 None. 

4116 FUTURE DIRECTIONS 

4117 None. 

4118 SEE ALSO 

4119 aio_cancel(), aio_error(), aioJsync{), aio_read(), aio_write(), close (), _exit (), exec, fork (), liojistio (), 

4120 lseek( ), read (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <aio.h> 

4121 CHANGE HISTORY 

4122 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

4123 Issue 6 

4124 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

4125 implementation does not support the _POSIX_ASYNCHRONOUS_IO option. 

4126 The APPLICATION USAGE section is added. 

4127 The [EINVAL] error condition is updated as a "may fail". This is for consistency with the 

4128 DESCRIPTION. 
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4129 NAME 

4130 aio_suspend — wait for an asynchronous I/O request (REALTIME) 

4131 SYNOPSIS 

4132 aio #include <aio.h> 

4133 int aio_suspend(const struct aiocb * const list[], int nent, 

4134 const struct timespec * timeout) ; 

4135 


4136 DESCRIPTION 


4137 

4138 

4139 

4140 

4141 

4142 

4143 

4144 

4145 

4146 

4147 


The aio_suspend() function shall suspend the calling thread until at least one of the asynchronous 
I/O operations referenced by the list argument has completed, until a signal interrupts the 
function, or, if timeout is not NULL, until the time interval specified by timeout has passed. If any 
of the aiocb structures in the list correspond to completed asynchronous I/O operations (that is, 
the error status for the operation is not equal to [EINPROGRESS]) at the time of the call, the 
function shall return without suspending the calling thread. The list argument is an array of 
pointers to asynchronous I/O control blocks. The nent argument indicates the number of 
elements in the array. Each aiocb structure pointed to has been used in initiating an 
asynchronous I/O request via aio_read(), aio_write(), or lio_listio(). This array may contain 
NULL pointers, which are ignored. If this array contains pointers that refer to aiocb structures 
that have not been used in submitting asynchronous I/O, the effect is undefined. 


4148 

4149 

4150 MON 

4151 


If the time interval indicated in the timespec structure pointed to by timeout passes before any of 
the I/O operations referenced by list are completed, then aio_snspend{) shall return with an 
error. If the Monotonic Clock option is supported, the clock that shall be used to measure this I 
time interval shall be the CLOCK_MONOTONIC clock. I 


4152 RETURN VALUE 

4153 If the aio_suspend() function returns after one or more asynchronous I/O operations have 

4154 completed, the function shall return zero. Otherwise, the function shall return a value of -1 and 

4155 set errno to indicate the error. 


4156 The application may determine which asynchronous I/O completed by scanning the associated 

4157 error and return status using aio_error( ) and aio_retnrn (), respectively. 

4158 ERRORS 

4159 The aio_suspend () function shall fail if: 


4160 

4161 

[EAGAIN] 

No asynchronous I/O indicated in the list referenced by list completed in the 
time interval indicated by timeout. 

4162 

4163 

4164 

4165 

[EINTR] 

A signal interrupted the aio_snspend{) function. Note that, since each 
asynchronous I/O operation may possibly provoke a signal when it 
completes, this error return may be caused by the completion of one (or more) 
of the very I/O operations being awaited. 

4166 

4167 

EXAMPLES 

None. 


4168 

4169 

4170 

APPLICATION USAGE 

The aio_suspend() function is part of the _POSIX_ASYNCHRONOUS_IO option and need not be 
available on all implementations. 

4171 

4172 

RATIONALE 

None. 
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4173 FUTURE DIRECTIONS 

4174 None. 

4175 SEE ALSO 

4176 aio_read(), aio_write (), lio_listio(), the System Interface Definitions volume of 

4177 IEEE Std. 1003.1-200x, <aio.h> 

4178 CHANGE HISTORY 

4179 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 

4180 Issue 6 

4181 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

4182 implementation does not support the _POSIX_ASYNCHRONOUS_IO option. 

4183 The APPLICATION USAGE section is added. I 

4184 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that the I 

4185 CLOCK_MONOTONIC clock, if supported, is used. I 
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4186 NAME 

4187 aio_write — asynchronous write to a file (REALTIME) 

4188 SYNOPSIS 

4189 AIO #include <aio.h> 

4190 int aio_write (struct aiocb *aiocbp); 

4191 

4192 DESCRIPTION 

4193 The aio_ivrite() function allows the calling process to write aiocbp ~^aio_nbytes to the file 

4194 associated with aiocbp-^aioffildes from the buffer pointed to by aiocbp-^>ciio_bnf. The function call 

4195 shall return when the write request has been initiated or, at a minimum, queued to the file or 

4196 device. 

4197 pio If prioritized I/O is supported for this file, then the asynchronous operation shall be submitted 

4198 at a priority equal to the scheduling priority of the process minus aiocbp-^aio_reqprio. 

4199 The aiocbp may be used as an argument to aio_error( ) and aiojreturn () in order to determine the 

4200 error status and return status, respectively, of the asynchronous operation while it is proceeding. 

4201 The aiocbp argument points to an aiocb structure. If the buffer pointed to by aiocbp-^aiojmf or 

4202 the control block pointed to by aiocbp becomes an illegal address prior to asynchronous I/O 

4203 completion, then the behavior is undefined. 

4204 If 0_APPEND is not set for the file descriptor aioffildes , then the requested operation takes place 

4205 at the absolute position in the file as given by aio_offset, as if lseek () were called immediately 

4206 prior to the operation with an offset equal to aiojoffset and a whence equal to ]SEEK_SET). If 

4207 0_APPEND is set for the file descriptor, write operations append to the file in the same order as 

4208 the calls were made. After a successful call to enqueue an asynchronous I/O operation, the value 

4209 of the file offset for the file is unspecified. 

4210 The aiocbp->aio_lio_opcode field shall be ignored by aio_zvrite( ). 

4211 Simultaneous asynchronous operations using the same aiocbp produce undefined results. 

4212 sio If synchronized I/O is enabled on the file associated with aiocbp —hi ioffildes , the behavior of this 

4213 function shall be according to the definitions of synchronized I/O data integrity completion, and 

4214 synchronized I/O file integrity completion. 

4215 For any system action that changes the process memory space while an asynchronous I/O is 

4216 outstanding to the address range being changed, the result of that action is undefined. 

4217 man For regular files, no data transfer shall occur past the offset maximum established in the open 

4218 file description associated with aiocbp-^aioffildes. 

4219 RETURN VALUE 

4220 The aio_zvrite() function shall return the value zero to the calling process if the I/O operation is 

4221 successfully queued; otherwise, the function shall return the value -1 and set errno to indicate 

4222 the error. 

4223 ERRORS 

4224 The aio_zvrite() function shall fail if: 

4225 [E AG AIN] The requested asynchronous I/O operation was not queued due to system 

4226 resource limitations. 

4227 Each of the following conditions may be detected synchronously at the time of the call to 

4228 aio_write(), or asynchronously. If any of the conditions below are detected synchronously, the 

4229 aio_ivrite() function shall return -1 and set errno to the corresponding value. If any of the 
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4230 conditions below are detected asynchronously, the return status of the asynchronous operation 

4231 shall be set to -1, and the error status of the asynchronous operation is set to the corresponding 

4232 value. 

4233 [EBADF] The aiocbp-^aiojildes argument is not a valid file descriptor open for writing. 

4234 [EINVAL] The file offset value implied by aiocbp—i>aio_of)set would be invalid, 

4235 aiocbp-^aio_reqprio is not a valid value, or aiocbp-^aio_nbytes is an invalid 

4236 value. 

4237 In the case that the aio_zvrite() successfully queues the I/O operation, the return status of the 

4238 asynchronous operation shall be one of the values normally returned by the write( ) function call. 

4239 If the operation is successfully queued but is subsequently canceled or encounters an error, the 

4240 error status for the asynchronous operation contains one of the values normally set by the 

4241 ivrite( ) function call, or one of the following: 

4242 [EBADF] The aiocbp-^aiojildes argument is not a valid file descriptor open for writing. 

4243 [EINVAL] The file offset value implied by aiocbp-^aio_offset would be invalid. 

4244 [ECANCELED] The requested I/O was canceled before the I/O completed due to an explicit 

4245 aio_cancel () request. 

4246 man The following condition may be detected synchronously or asynchronously: 

4247 [EFBIG] The file is a regular file, aiobcp-^aio_nbytes is greater than 0, and the starting 

4248 offset in aiobcp-^aio_offset is at or beyond the offset maximum in the open file 

4249 description associated with aiocbp-^aiojildes. 

4250 EXAMPLES 

4251 None. 

4252 APPLICATION USAGE 

4253 The aio_write() function is part of the _POSIX_ASYNCHRONOUS_IO option and need not be 

4254 available on all implementations. 

4255 RATIONALE 

4256 None. 

4257 FUTURE DIRECTIONS 

4258 None. 

4259 SEE ALSO 

4260 aio_cancel(), aio_error(), aio_read(), aio_return(), close(), _exit(), exec, fork (), lio_listio(), lseek(), 

4261 ivrite( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <aio.h> 

4262 CHANGE HISTORY 

4263 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

4264 Large File Summit extensions are added. 

4265 Issue 6 

4266 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

4267 implementation does not support the _POSIX_ASYNCHRONOUS_IO option. 

4268 The APPLICATION USAGE section is added. 

4269 The following new requirements on POSIX implementations derive from alignment with the 

4270 Single UNIX Specification: 

4271 • In the DESCRIPTION, text is added to indicate that for regular files no data transfer occurs 

4272 past the offset maximum established in the open file description associated with 
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4273 aiocbp-^aiojildes. 

4274 • The [EFBIG] error is added as part of the large file support extensions. 
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4275 NAME 

4276 alarm — schedule an alarm signal 

4277 SYNOPSIS 

4278 #include <unistd.h> 

4279 unsigned int alarm (unsigned int seconds) ; 

4280 DESCRIPTION 

4281 The alarm () function shall cause the system to generate a SIGALRM signal for the process after 

4282 the number of realtime seconds specified by seconds have elapsed. Processor scheduling delays 

4283 may prevent the process from handling the signal as soon as it is generated. 

4284 If seconds is 0, a pending alarm request, if any, is canceled. 

4285 Alarm requests are not stacked; only one SIGALRM generation can be scheduled in this manner. 

4286 If the SIGALRM signal has not yet been generated, the call shall result in rescheduling the time 

4287 at which the SIGALRM signal is generated. 

4288 man Interactions between alarm () and any of setitimer (), ualarm (), or nsleep() are unspecified. 

4289 RETURN VALUE 

4290 If there is a previous alarm () request with time remaining, alarm () shall return a non-zero value 

4291 that is the number of seconds until the previous request would have generated a SIGALRM 

4292 signal. Otherwise, alarm () shall return 0. 

4293 ERRORS 

4294 The alarm () function is always successful, and no return value is reserved to indicate an error. 

4295 EXAMPLES 

4296 None. 

4297 APPLICATION USAGE 

4298 Th e fork () function clears pending alarms in the child process. A new process image created by 

4299 one of the exec functions inherits the time left to an alarm signal in the old process' image. 

4300 Application writers should note that the type of the argument seconds and the return value of 

4301 alarm () is unsigned int. That means that a Strictly Conforming POSIX System Interfaces 

4302 Application cannot pass a value greater than the minimum guaranteed value for |UINT_MAX}, 

4303 which the ISO C standard sets as 65 535, and any application passing a larger value is restricting 

4304 its portability. A different type was considered, but historical implementations, including those 

4305 with a 16-bit int type, consistently use either unsigned int or int. 

4306 Application writers should be aware of possible interactions when the same process uses both 

4307 the alarm () and sleep () functions. 

4308 RATIONALE 

4309 Many historical implementations (including Version 7 and System V) allow an alarm to occur up 

4310 to a second early. Other implementations allow alarms up to half a second or one clock tick 

4311 early or do not allow them to occur early at all. The latter is considered most appropriate, since it 

4312 gives the most predictable behavior, especially since the signal can always be delayed for an 

4313 indefinite amount of time due to scheduling. Applications can thus choose the seconds argument 

4314 as the minimum amount of time they wish to have elapse before the signal. 

4315 The term realtime here and elsewhere (sleep (), times ()) is intended to mean "wall clock" time as 

4316 common English usage, and has nothing to do with "realtime operating systems". It is in 

4317 contrast to virtual time, which could be misinterpreted if just time were used. 

4318 In some implementations, including 4.3 BSD, very large values of the seconds argument are 

4319 silently rounded down to an implementation-dependent maximum value. This maximum is 
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4320 large enough (on the order of several months) that the effect is not noticeable. 

4321 There were two possible choices for alarm generation in multi-threaded applications: generation I 

4322 for the calling thread or generation for the process. The first option would not have been 

4323 particularly useful since the alarm state is maintained on a per-process basis and the alarm that 

4324 is established by the last invocation of alarm () is the only one that would be active. 

4325 Furthermore, allowing generation of an asynchronous signal for a thread would have introduced 

4326 an exception to the overall signal model. This requires a compelling reason in order to be 

4327 justified. I 

4328 FUTURE DIRECTIONS 

4329 None. 

4330 SEE ALSO 

4331 alarm(), exec, fork(), getitimer{), pause(), sigaction(), sleep(), nalarm(), usleep{), the System I 

4332 Interface Definitions volume of IEEE Std. 1003.1-200x, <signal.h>, <unistd.h> 

4333 CHANGE HISTORY 

4334 First released in Issue 1. 

4335 Derived from Issue 1 of the SVID. 

4336 Issue 4 

4337 The <unistd.h> header is included in the SYNOPSIS section. 

4338 Issue 4, Version 2 

4339 The DESCRIPTION is updated to indicate that interactions with the setitimer( ), ualann( ), and 

4340 asleep {) functions are unspecified. 

4341 Issue 6 

4342 The following new requirements on POSIX implementations derive from alignment with the 

4343 Single UNIX Specification: 

4344 • The DESCRIPTION is updated to indicate that interactions with the setitimer (), ualarni (), and 

4345 asleep () functions are unspecified. 
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4346 NAME 

4347 asctime, asctime_r — convert date and time to a string 

4348 SYNOPSIS 

4349 tinclude <time.h> 

4350 char *asctime (const struct tm *timeptr) ; 

4351 TSF char *asctime_r (const struct tm *tm, char *buf) ; 

4352 


4353 DESCRIPTION 

4354 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

4355 conflict between the requirements described here and the ISO C standard is unintentional. This I 

4356 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

4357 The asctime () function shall convert the broken-down time in the structure pointed to by timeptr 

4358 into a string in the form: 

4359 Sun Sep 16 01:03:52 1973\n\0 

4360 using the equivalent of the following algorithm: 


4361 

char *asctime(const struct 

tm *timeptr) 

4362 

{ 




4363 

static char 

wday_name[7 

] [3] = { 


4364 

"Sun", 

"Mon", "Tue" 

, "Wed", 

"Thu", "Fri", "Sat" 

4365 

}; 




4366 

static char 

mon_name[12 

] [3] = { 


4367 

"Jan", 

"Feb", "Mar" 

, "Apr", 

"May", "Jun", 

4368 

"Jul", 

"Aug", "Sep" 

, "Oct", 

"Nov", "Dec" 

4369 

}; 




4370 

static char 

result[26]; 



4371 

sprintf(result, "%.3s % 

. 3 s % 3 d % . 

. 2d:%.2d:%.2d %d\n". 


4372 

4373 

4374 

4375 

4376 

4377 

4378 


wday_name [timeptr-atm_wday ] , 
mon_name [timeptr—>tm_mon] , 
timept r—>tm_mday, timept r—»tm_hour, 
timeptr—>tm_min, t imept r-4tm_sec, 
1900 + timeptr—»tm_year); 
return result; 


4379 


The tm structure is defined in the <time.h> header. 


4380 cx The asctime (), ctime (), gmtime( ), and localtime () functions shall return values in one of two static 

4381 objects: a broken-down time structure and an array of type char. Execution of any of the 

4382 functions may overwrite the information returned in either of these objects by any of the other 

4383 functions. 

4384 The asctime () function need not be reentrant. A function that is not required to be reentrant is not 

4385 required to be thread-safe. 

4386 tsf The asctime_r( ) function shall convert the broken-down time in the structure pointed to by tm 

4387 into a string (of the same form as that returned by asctime ()) that is placed in the user-supplied 

4388 buffer pointed to by buf (which contains at least 26 bytes) and then return buf. 
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4389 RETURN VALUE 

4390 Upon successful completion, asctime( ) shall return a pointer to the string. 

4391 tsf Upon successful completion, asctime_r( ) shall return a pointer to a character string containing 

4392 the date and time. This string is pointed to by the argument buf. If the function is unsuccessful, 

4393 it shall return NULL. 

4394 ERRORS 

4395 No errors are defined. 

4396 EXAMPLES 

4397 None. 

4398 APPLICATION USAGE 

4399 Values for the broken-down time structure can be obtained by calling gmtime( ) or localtime(). 

4400 This function is included for compatibility with older implementations, and does not support 

4401 localized date and time formats. Applications should use strftime( ) to achieve maximum 

4402 portability. 

4403 The asctime_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 

4404 of possibly using a static data area that may be overwritten by each call. 

4405 RATIONALE 

4406 None. 

4407 FUTURE DIRECTIONS 

4408 None. 

4409 SEE ALSO 

4410 clock(), ctime(), difftime (), gmtime( ), localtime(), mktime(), strftime{), strptime(), time(), utime (), 

4411 the System Interface Definitions volume of IEEE Std. 1003.1-200x, <time.h> 

4412 CHANGE HISTORY 

4413 First released in Issue 1. 

4414 Derived from Issue 1 of the SVID. 

4415 Issue 4 

4416 The location of the tm structure is now defined. 

4417 The APPLICATION USAGE section is expanded to describe the time-handling functions 

4418 generally and to refer users to strftime( ), which is a locale-dependent time-handling function. 

4419 The following change is incorporated for alignment with the ISO C standard: 

4420 • The type of argument timeptr is changed from struct tm* to const struct tm*. 

4421 Issue 5 

4422 Normative text previously in the APPLICATION USAGE section is moved to the 

4423 DESCRIPTION. 

4424 The asctime_r( ) function is included for alignment with the POSIX Threads Extension. 

4425 A note indicating that the asctime() function need not be reentrant is added to the 

4426 DESCRIPTION. 

4427 Issue 6 

4428 The asctime_r( ) function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS option. 

4429 Extensions beyond the ISO C standard are now marked. 
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4430 

4431 

4432 


The APPLICATION USAGE section is updated to include a note on the thread-safe function and 
its avoidance of possibly using a static data area. 

The DESCRIPTION of asctime_r () is updated to describe the format of the string returned. 
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4433 NAME 

4434 asin — arc sine function 

4435 SYNOPSIS 

4436 #include <math.h> 

4437 double asin (double x) ; 

4438 DESCRIPTION 

4439 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

4440 conflict between the requirements described here and the ISO C standard is unintentional. This I 

4441 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

4442 The asin () function shall compute the principal value of the arc sine of x. The value of x should 

4443 be in the range [-1,1]. 

4444 An application wishing to check for error situations should set errno to 0, then call asin (). If errno 

4445 is non-zero on return, or the return value is NaN, an error has occurred. 

4446 RETURN VALUE 

4447 Upon successful completion, asin () shall return the arc sine of x, in the range [-Jt/2,Jt/2] radians. 

4448 xsi If the value of x is not in the range [-1,1], and is not ±Inf or NaN, either 0.0 or NaN shall be 

4449 returned and errno shall be set to [EDOM]. 

4450 xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

4451 If x is ±Inf, either 0.0 shall be returned and errno set to [EDOM], or NaN shall be returned and 

4452 errno may be set to [EDOM]. 

4453 If the result underflows, 0.0 shallbe returned and errno may be set to [ERANGE]. 

4454 ERRORS 

4455 The asin () function shall fail if: 

4456 xsi [EDOM] The value x is not ±Inf or NaN andis not in the range [-1,1]. 

4457 The asin () function may fail if: 

4458 xsi [EDOM] The value of x is ±Inf or NaN. 

4459 [ERANGE] The result underflows 

4460 xsi No other errors shall occur. 

4461 EXAMPLES 

4462 None. 

4463 APPLICATION USAGE 

4464 None. 

4465 RATIONALE 

4466 None. 

4467 FUTURE DIRECTIONS 

4468 None. 

4469 SEE ALSO 

4470 isnan (), sin (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 
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4471 CHANGE HISTORY 

4472 First released in Issue 1. 

4473 Derived from Issue 1 of the SVID. 

4474 Issue 4 

4475 References to matherr {) are removed. 

4476 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

4477 ISO C standard and to rationalize error handling in the mathematics functions. 

4478 The return value specified for [EDOM] is marked as an extension. 

4479 Issue 5 

4480 The DESCRIPTION is updated to indicate how an application should check for an error. This 

4481 text was previously published in the APPLICATION USAGE section. 
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4482 NAME 

4483 asinh — hyperbolic arc sine 

4484 SYNOPSIS 

4485 xsi #include <math.h> 

4486 double asinh (double x) ; 

4487 

4488 DESCRIPTION 

4489 Refer to acosh (). 
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4490 NAME 

4491 assert — insert program diagnostics 

4492 SYNOPSIS 

4493 tinclude <assert.h> 

4494 void assert (int expression) ; 

4495 DESCRIPTION 

4496 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

4497 conflict between the requirements described here and the ISO C standard is unintentional. This I 

4498 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

4499 The assert() macro inserts diagnostics into programs. When it is executed, if expression is false 

4500 (that is, compares equal to 0), assert {) writes information about the particular call that failed 

4501 (including the text of the argument, the name of the source file, and the source file line 

4502 number—the latter are respectively the values of the preprocessing macros __FILE__ and 

4503 _ _LINE_ _) on stderr and calls abort (). 

4504 Forcing a definition of the name NDEBUG, either from the compiler command line or with the 

4505 preprocessor control statement #define NDEBUG ahead of the #include <assert.h> statement, 

4506 shall stop assertions from being compiled into the program. 

4507 RETURN VALUE 

4508 The assert () macro shall return no value. 

4509 ERRORS 

4510 No errors are defined. 

4511 EXAMPLES 

4512 None. 

4513 APPLICATION USAGE 

4514 None. 

4515 RATIONALE 

4516 None. 

4517 FUTURE DIRECTIONS 

4518 None. 

4519 SEE ALSO 

4520 abort( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <assert.h>, stderr 

4521 CHANGE HISTORY 

4522 First released in Issue 1. 

4523 Derived from Issue 1 of the SVID. 

4524 Issue 4 

4525 The APPLICATION USAGE section is merged into the DESCRIPTION. 
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4526 NAME 

4527 atan — arc tangent function 

4528 SYNOPSIS 

4529 #include <math.h> 

4530 double atan (double x) ; 

4531 DESCRIPTION 

4532 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

4533 conflict between the requirements described here and the ISO C standard is unintentional. This I 

4534 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

4535 The atan () function shall compute the principal value of the arc tangent of x. 

4536 An application wishing to check for error situations should set errno to 0 before calling atan (). If 

4537 errno is non-zero on return, or the return value is NaN, an error has occurred. 

4538 RETURN VALUE 

4539 Upon successful completion, atan() shall return the arc tangent of x in the range [-7t/2,Jt/2] 

4540 radians. 

4541 xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

4542 If the result underflows, 0.0 shall be returned and errno may be set to [ERANGE]. 

4543 ERRORS 

4544 The atan () function may fail if: 

4545 xsi [EDOM] The value of x is NaN. 

4546 [ERANGE] The result underflows 

4547 xsi No other errors shall occur. 

4548 EXAMPLES 

4549 None. 

4550 APPLICATION USAGE 

4551 None. 

4552 RATIONALE 

4553 None. 

4554 FUTURE DIRECTIONS 

4555 None. 

4556 SEE ALSO 

4557 atan2(), isnan (), tan(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

4558 <math.h> 

4559 CHANGE HISTORY 

4560 First released in Issue 1. 

4561 Derived from Issue 1 of the SVID. 

4562 Issue 4 

4563 References to matherr( ) are removed. 

4564 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

4565 ISO C standard and to rationalize error handling in the mathematics functions. 
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4566 

4567 

4568 

4569 


The return value specified for [EDOM] is marked as an extension. 

Issue 5 

The DESCRIPTION is updated to indicate how an application should check for an error. This 
text was previously published in the APPLICATION USAGE section. 
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4570 NAME 

4571 atan2 — arc tangent function 

4572 SYNOPSIS 

4573 #include <math.h> 

4574 double atan2 (double y, double x) ; 

4575 DESCRIPTION 

4576 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

4577 conflict between the requirements described here and the ISO C standard is unintentional. This I 

4578 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

4579 The atari 2 () function shall compute the principal value of the arc tangent of y /x, using the signs 

4580 of both arguments to determine the quadrant of the return value. 

4581 An application wishing to check for error situations should set errno to 0 before calling atan2 (). 

4582 If errno is non-zero on return, or the return value is NaN, an error has occurred. 

4583 RETURN VALUE 

4584 Upon successful completion, atan2() shall return the arc tangent of y/x in the range 

4585 radians. If both arguments are 0.0, an implementation-dependent value is returned and errno 

4586 may be set to [EDOM]. 

4587 xsi If x or y is NaN, NaN shall be returned and errno may be set to [EDOM]. 

4588 If the result underflows, 0.0 shall be returned and errno may be set to [ERANGE]. 

4589 ERRORS 

4590 The atan2 () function may fail if: 

4591 xsi [EDOM] Both arguments are 0.0 or one or more of the arguments is NaN. 

4592 [ERANGE] The result underflows 

4593 xsi No other errors shall occur. 

4594 EXAMPLES 

4595 None. 

4596 APPLICATION USAGE 

4597 None. 

4598 RATIONALE 

4599 None. 

4600 FUTURE DIRECTIONS 

4601 None. 

4602 SEE ALSO 

4603 atan(), isnan (), tan(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

4604 <math.h> 

4605 CHANGE HISTORY 

4606 First released in Issue 1. 

4607 Derived from Issue 1 of the SVID. 

4608 Issue 4 

4609 References to matherri ) are removed. 

4610 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

4611 ISO C standard and to rationalize error handling in the mathematics functions. 
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4612 

4613 

4614 

4615 


The return value specified for [EDOM] is marked as an extension. 

Issue 5 

The DESCRIPTION is updated to indicate how an application should check for an error. This 
text was previously published in the APPLICATION USAGE section. 
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4616 NAME 

4617 atanh — hyperbolic arc tangent 

4618 SYNOPSIS 

4619 xsi #include <math.h> 

4620 double atanh (double x) ; 

4621 

4622 DESCRIPTION 

4623 Refer to acosh (). 


144 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


atexit() 


4624 NAME 

4625 atexit — register a function to run at process termination 

4626 SYNOPSIS 

4627 #include <stdlib.h> 

4628 int atexit (void (* func) (void) ) ; 

4629 DESCRIPTION 

4630 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

4631 conflict between the requirements described here and the ISO C standard is unintentional. This I 

4632 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

4633 The atexit () function registers the function pointed to by func to be called without arguments. At 

4634 normal process termination, functions registered by atexit ( ) shall be called in the reverse order to 

4635 that in which they were registered. Normal termination occurs either by a call to exit() or a 

4636 return from main (). 

4637 At least 32 functions can be registered with atexit (). 

4638 cx After a successful call to any of the exec functions, any functions previously registered by atexit () 

4639 shall no longer be registered. 

4640 RETURN VALUE 

4641 Upon successful completion, atexit ( ) shall return 0; otherwise, it shall return a non-zero value. 

4642 ERRORS 

4643 No errors are defined. 

4644 EXAMPLES 

4645 None. 

4646 APPLICATION USAGE 

4647 The functions registered by a call to atexit () must return to ensure that all registered functions 

4648 are called. 

4649 The application should call sysconf() to obtain the value of {ATEXIT_MAX}, the number of 

4650 functions that can be registered. There is no way for an application to tell how many functions 

4651 have already been registered with atexit ( ). 

4652 RATIONALE 

4653 None. 

4654 FUTURE DIRECTIONS 

4655 None. 

4656 SEE ALSO 

4657 exit ( ), sysconf( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

4658 CHANGE HISTORY 

4659 First released in Issue 4. 

4660 Derived from the ANSI C standard. 

4661 Issue 4, Version 2 

4662 The APPLICATION USAGE section is updated to indicate how an application can determine the 

4663 setting of {ATEXIT_MAX}, which is a constant added for X/OPEN UNIX conformance. 
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4664 Issue 6 

4665 Extensions beyond the ISO C standard are now marked. 
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4666 NAME 

4667 atof — convert a string to double-precision number 

4668 SYNOPSIS 

4669 #include <stdlib.h> 

4670 double atof (const char *str) ; 

4671 DESCRIPTION 

4672 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

4673 conflict between the requirements described here and the ISO C standard is unintentional. This I 

4674 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

4675 The call atof(str) shall be equivalent to: 

4676 strtod (str, (char **)NULL), 

4677 except that the handling of errors may differ. If the value cannot be represented, the behavior is 

4678 undefined. 

4679 RETURN VALUE 

4680 The atof( ) function shall return the converted value if the value can be represented. 

4681 ERRORS 

4682 No errors are defined. 

4683 EXAMPLES 

4684 None. 

4685 APPLICATION USAGE 

4686 The atof() function is subsumed by strtod() but is retained because it is used extensively in 

4687 existing code. If the number is not known to be in range, strtod () should be used because atof( ) is 

4688 not required to perform any error checking. 

4689 RATIONALE 

4690 None. 

4691 FUTURE DIRECTIONS 

4692 None. 

4693 SEE ALSO 

4694 strtod( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

4695 CHANGE HISTORY 

4696 First released in Issue 1. 

4697 Derived from Issue 1 of the SVID. 

4698 Issue 4 

4699 Reference to how str is converted is removed from the DESCRIPTION. 

4700 The APPLICATION USAGE section is added. 

4701 The following change is incorporated for alignment with the ISO C standard: 

4702 • The type of argument str is changed from char* to const char*. 
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4703 NAME 

4704 atoi — convert a string to an integer 

4705 SYNOPSIS 

4706 #include <stdlib.h> 

4707 int atoi (const char *str) ; 

4708 DESCRIPTION 

4709 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

4710 conflict between the requirements described here and the ISO C standard is unintentional. This I 

4711 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

4712 The call atoi ( str ) shall be equivalent to: 

4713 (int) strtol(str, (char **)NULL, 10) 

4714 except that the handling of errors may differ. If the value cannot be represented, the behavior is 

4715 undefined. 

4716 RETURN VALUE 

4717 The atoi ( ) function shall return the converted value if the value can be represented. 

4718 ERRORS 

4719 No errors are defined. 

4720 EXAMPLES 

4721 Converting an Argument 

4722 The following example checks for proper usage of the program. If there is an argument and the 

4723 decimal conversion of this argument (obtained using atoi()) is greater than 0, then the program 

4724 has a valid number of minutes to wait for an event. 

4725 #include <stdlib.h> 

4726 #include <stdio.h> 

4727 

4728 int minutes_to_event; 

4729 

4730 if (argc < 2 | | ( (minutes_to_event = atoi (argv[l]))> <= 0) { 

4731 fprintf (stderr, "Usage: %s minutes\n", argv[0]); exit(l); 

4732 } 

4733 

4734 APPLICATION USAGE 

4735 The atoi() function is subsumed by strtol() but is retained because it is used extensively in 

4736 existing code. If the number is not known to be in range, strtol ( ) should be used because atoi ( ) is 

4737 not required to perform any error checking. 

4738 RATIONALE 

4739 None. 

4740 FUTURE DIRECTIONS 

4741 None. 

4742 SEE ALSO 

4743 strtol (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 
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4744 CHANGE HISTORY 

4745 First released in Issue 1. 

4746 Derived from Issue 1 of the SVID. 

4747 Issue 4 

4748 Reference to how str is converted is removed from the DESCRIPTION. 

4749 The APPLICATION USAGE section is added. 

4750 The following change is incorporated for alignment with the ISO C standard: 

4751 • The type of argument str is changed from char’'' to const char 51 '. 
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4752 NAME 

4753 atol — convert a string to a long integer 

4754 SYNOPSIS 

4755 #include <stdlib.h> 

4756 long int atol (const char *str) ; 

4757 DESCRIPTION 

4758 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

4759 conflict between the requirements described here and the ISO C standard is unintentional. This I 

4760 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

4761 The call atol (str ) shall be equivalent to: 

4762 strtol(str, (char **)NULL, 10) 

4763 except that the handling of errors may differ. If the value cannot be represented, the behavior is 

4764 undefined. 

4765 RETURN VALUE 

4766 The atol ( ) function shall return the converted value if the value can be represented. 

4767 ERRORS 

4768 No errors are defined. 

4769 EXAMPLES 

4770 None. 

4771 APPLICATION USAGE 

4772 The atol() function is subsumed by strtol() but is retained because it is used extensively in 

4773 existing code. If the number is not known to be in range, strtol () should be used because atol () is 

4774 not required to perform any error checking. 

4775 RATIONALE 

4776 None. 

4777 FUTURE DIRECTIONS 

4778 None. 

4779 SEE ALSO 

4780 strtol (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

4781 CHANGE HISTORY 

4782 First released in Issue 1. 

4783 Derived from Issue 1 of the SVID. 

4784 Issue 4 

4785 Reference to how str is converted is removed from the DESCRIPTION. 

4786 The APPLICATION USAGE section is added. 

4787 The following changes are incorporated for alignment with the ISO C standard: 

4788 • The type of argument str is changed from char* to const char*. 

4789 • The return type of the function is expanded to long int. 
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4790 NAME 

4791 basename — return the last component of a path name 

4792 Notes to Reviewers 

4793 This section ivith side shading will not appear in the final copy. - Ed. 

4794 It is recommended that basename () and dirname() become mandatory, as POSIX.2 includes 

4795 counterpart utilities. 

4796 SYNOPSIS 

4797 xsi tinclude <libgen.h> 

4798 char ‘basename (char *path) ; 

4799 

4800 DESCRIPTION 

4801 The basename( ) function shall take the path name pointed to by path and return a pointer to the 

4802 final component of the path name, deleting any trailing ' /' characters. 

4803 If the string consists entirely of the ' /' character, basename ( ) shall return a pointer to the string 

4804 " / ". 

4805 If path is a null pointer or points to an empty string, basename () shall return a pointer to the 

4806 string " . 

4807 The basename () function may modify the string pointed to by path, and may return a pointer to 

4808 static storage that may then be overwritten by a subsequent call to basename( ). 

4809 The basename () function need not be reentrant. A function that is not required to be reentrant is 

4810 not required to be thread-safe. 

4811 RETURN VALUE 

4812 The basename () function shall return a pointer to the final component of path. 

4813 ERRORS 

4814 No errors are defined. 

4815 EXAMPLES 

4816 Using basenamet ) 

4817 The following program fragment returns a pointer to the value lib, which is the base name of 

4818 /usr/lib. 

4819 #include <libgen.h> 

4820 

4821 char ‘name = "/usr/lib"; 

4822 char *base; 

4823 base = basename (name) ; 

4824 
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4825 Sample Input and Output Strings for basenamel) 

4826 In the following table, the input string is the value pointed to by path , and the output string is 

4827 the return value of the basename () function. 


4828 

Input String 

Output String 

4829 

"/usr/lib" 

"lib" 

4830 

"/usr/" 

"usr" 

4831 

II j II 

M j II 


4832 APPLICATION USAGE 

4833 None. 

4834 RATIONALE 

4835 None. 

4836 FUTURE DIRECTIONS 

4837 None. 

4838 SEE ALSO 

4839 dir name ( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <libgen.h> 

4840 CHANGE HISTORY 

4841 First released in Issue 4, Version 2. 

4842 Issue 5 

4843 Moved from X/OPEN UNIX extension to BASE. 

4844 Normative text previously in the APPLICATION USAGE section is moved to the 

4845 DESCRIPTION. 

4846 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 

4847 Issue 6 

4848 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 
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4849 NAME 

4850 bcmp — memory operations (LEGACY) 

4851 SYNOPSIS 

4852 xsi #include <strings.h> 

4853 int bcmp (const void *sl, const void *s2, size_t n) ; 

4854 

4855 DESCRIPTION 

4856 The bcmp () function shall compare the first n bytes of the area pointed to by si with the area 

4857 pointed to by s2. 

4858 RETURN VALUE 

4859 The bcmp () function shall return 0 if si and s2 are identical; otherwise, it shall return non-zero. 

4860 Both areas are assumed to be n bytes long. If the value of n is 0, bcmp( ) shall return 0. 

4861 ERRORS 

4862 No errors are defined. 

4863 EXAMPLES 

4864 None. 

4865 APPLICATION USAGE 

4866 memcmpt ) is preferred over this function. 

4867 For maximum portability, it is recommended to replace the function call to bcmp( ) as follows: 

4868 tdefine bcmp (bl, b2, len) memcmp((bl), (b2), (size_t) (len) ) 

4869 RATIONALE 

4870 None. 

4871 FUTURE DIRECTIONS 

4872 This function may be withdrawn in a future version. 

4873 SEE ALSO 

4874 memcmp{ ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <strings.h> 

4875 CHANGE HISTORY 

4876 First released in Issue 4, Version 2. 

4877 Issue 5 

4878 Moved from X/OPEN UNIX extension to BASE. 

4879 Issue 6 

4880 This function is marked LEGACY. 


System Interfaces, Issue 6 


153 



bcopyO 


System Interfaces 


4881 NAME 

4882 bcopy — memory operations (LEGACY) 

4883 SYNOPSIS 

4884 xsi #include <strings.h> 

4885 void bcopy (const void *sl, void *s2, size_t n) ; 

4886 

4887 DESCRIPTION 

4888 The bcopy () function shall copy n bytes from the area pointed to by si to the area pointed to by 

4889 s2. 

4890 The bytes are copied correctly even if the area pointed to by si overlaps the area pointed to by 

4891 s2. 

4892 RETURN VALUE 

4893 The bcopy () function shall return no value. 

4894 ERRORS 

4895 No errors are defined. 

4896 EXAMPLES 

4897 None. 

4898 APPLICATION USAGE 

4899 memmove{ ) is preferred over this function. 

4900 The following are approximately equivalent (note the order of the arguments): 

4901 bcopy (si, s2, n) ~= memmove (s2, si, n) 

4902 For maximum portability, it is recommended to replace the function call to bcopy () as follows: 

4903 #define bcopy (bl,b2, len) memmove ( (b2) , (bl), (size_t) (len) ) 

4904 RATIONALE 

4905 None. 

4906 FUTURE DIRECTIONS 

4907 This function may be withdrawn in a future version. 

4908 SEE ALSO 

4909 memmove {), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <strings.h> 

4910 CHANGE HISTORY 

4911 First released in Issue 4, Version 2. 

4912 Issue 5 

4913 Moved from X/OPEN UNIX extension to BASE. 

4914 Issue 6 

4915 This function is marked LEGACY. 
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4916 NAME 

4917 bind — bind a name to a socket 


4918 SYNOPSIS 

4919 tinclude <sys/socket.h> 


4920 int bind(int socket, const struct sockaddr * address, 

4921 socklen_t address_len) ; 


4922 DESCRIPTION 

4923 The bind () function shall assign a local socket address address to a socket identified by descriptor 

4924 socket that has no local socket address assigned. Sockets created with the socket () function are 

4925 initially unnamed; they are identified only by their address family. 

4926 The bind () function takes the following arguments: 


4927 socket 


Specifies the file descriptor of the socket to be bound. 


4928 address 

4929 

4930 


Points to a sockaddr structure containing the address to be bound to the 
socket. The length and format of the address depend on the address family of 
the socket. 


4931 address_len Specifies the length of the sockaddr structure pointed to by the address 

4932 argument. 


4933 The socket in use may require the process to have appropriate privileges to use the bind() 

4934 function. 


4935 RETURN VALUE 

4936 Upon successful completion, bind( ) shall return 0; otherwise, -1 shall be returned and errno set 

4937 to indicate the error. 


4938 ERRORS 

4939 The bind () function shall fail if: 


4940 [EADDRINUSE] 

4941 The specified address is already in use. 

4942 [EADDRNOTAVAIL] 

4943 The specified address is not available from the local machine. 


4944 

4945 

4946 


[EAFNOSUPPORT] 

The specified address is not a valid address for the address family of the 
specified socket. 


4947 

4948 

4949 

4950 


[EBADF] 

[EFAULT} 

[EINVAL] 


The socket argument is not a valid file descriptor. 

The address argument cannot be accessed. 

The socket is already bound to an address, and the protocol does not support 
binding to a new address; or the socket has been shut down. 


4951 [ENOTSOCK] The socket argument does not refer to a socket. 

4952 [EOPNOTSUPP] The socket type of the specified socket does not support binding to an 

4953 address. 


4954 If the address family of the socket is AF_UNIX, then bind () shall fail if: 


4955 

4956 

4957 


[EACCES] A component of the path prefix denies search permission, or the requested 

name requires writing in a directory with a mode that denies write 
permission. 
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4958 

[EDESTADDRREQ] or [EISDIR] 

1 

4959 


The address argument is a null pointer. 

1 

4960 

[EIO] 

An I/O error occurred. 

1 

4961 

[ELOOP] 

Too many symbolic links were encountered in translating the path name in 

1 

4962 


address. 

1 

4963 

[ENAMETOOLONG] 

1 

4964 


A component of a path name exceeded |NAME_MAX} characters, or an entire 

1 

4965 


path name exceeded {PATH_MAX} characters. 

1 

4966 

[ENOENT] 

A component of the path name does not name an existing file or the path 

1 

4967 


name is an empty string. 

1 

4968 

[ENOTDIR] 

A component of the path prefix of the path name in address is not a directory. 

1 

4969 

[EROFS] 

The name would reside on a read-only file system. 

1 

4970 

The bind() function may fail if: 

1 

4971 

[EACCES] 

The specified address is protected and the current user does not have 

1 

4972 


permission to bind to it. 

1 

4973 

[EINVAL] 

The addressjen argument is not a valid length for the address family. 

1 

4974 

[EISCONN] 

The socket is already connected. 

1 

4975 

[ENAMETOOLONG] 

1 

4976 


Path name resolution of a symbolic link produced an intermediate result 

1 

4977 


whose length exceeds {PATH_MAX}. 

1 

4978 

[ENOBUFS] 

Insufficient resources were available to complete the call. 

1 

4979 

xsr [ENOSR] 

There were insufficient STREAMS resources for the operation to complete. 

1 

4980 

EXAMPLES 


1 

4981 

None. 


1 

4982 

APPLICATION USAGE 


1 

4983 

An application program can retrieve the assigned socket name with the getsockname( ) function. 

1 

4984 

RATIONALE 


1 

4985 

None. 


1 

4986 

FUTURE DIRECTIONS 


1 

4987 

None. 


1 

4988 

SEE ALSO 


1 

4989 

connect(), getsockname(), listen^), socket (), the System Interface Definitions volume of 

1 

4990 

IEEE Std. 1003.1-200x, <sys/socket.h> 

1 

4991 

CHANGE HISTORY 


1 

4992 

First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 

1 
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4993 NAME 

4994 bsd_signal — simplified signal facilities 

4995 SYNOPSIS 

4996 xsi #include <signal.h> 

4997 void (*bsd_signal(int sig, void (* func) (int) > ) (int); 

4998 

4999 DESCRIPTION 

5000 The bsd_signal() function provides a partially compatible interface for programs written to 

5001 historical system interfaces (see APPLICATION USAGE). 

5002 The function call bsd_signal(sig, func) has an effect as if implemented as: 

5003 void (*bsd_signal(int sig, void (*func) (int))) (int) 

5004 { 

5005 struct sigaction act, oact; 

5006 act. sa_handler = func; 

5007 act. sa_flags = SA_RESTART; 

5008 sigemptyset (&act. sa_mask) ; 

5009 sigaddset(&act.sa_mask, sig); 

5010 if (sigaction (sig, &act, &oact) == -1) 

5011 return (SIG_ERR) ; 

5012 return (oact. sa_handler) ; 

5013 } 

5014 The handler function should be declared: 

5015 void handler (int sig); 

5016 where sig is the signal number. The behavior is undefined if func is a function that takes more 

5017 than one argument, or an argument of a different type. 

5018 RETURN VALUE 

5019 Upon successful completion, bsd_signal() shall return the previous action for sig. Otherwise, 

5020 SIG_ERR shall be returned and errno shall be set to indicate the error. 

5021 ERRORS 

5022 Refer to sigaction(). 

5023 EXAMPLES 

5024 None. 

5025 APPLICATION USAGE 

5026 This function is a direct replacement for the BSD signal () function for simple applications that 

5027 are installing a single-argument signal handler function. If a BSD signal handler function is being 

5028 installed that expects more than one argument, the application has to be modified to use 

5029 sigaction (). The bsd_signal() function differs from signal () in that the SA_RESTART flag is set 

5030 and the SA_RESETHAND is clear when bsd_signal() is used. The state of these flags is not 

5031 specified for signal (). 

5032 RATIONALE 

5033 None. 
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5034 FUTURE DIRECTIONS 

5035 None. 

5036 SEE ALSO 

5037 sigaction (), sigaddset(), sigemptyset (), signal (), the System Interface Definitions volume of 

5038 IEEE Std. 1003.1-200x, <signal.h> 

5039 CHANGE HISTORY 

5040 First released in Issue 4, Version 2. 

5041 Issue 5 

5042 Moved from X/OPEN UNIX extension to BASE. 
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5043 NAME 

5044 bsearch — binary search a sorted table 

5045 SYNOPSIS 

5046 tinclude <stdlib.h> 

5047 void *bsearch(const void *key, const void *base, size_t nel, 

5048 size_t width, int ( *compar) (const void *, const void *)); 

5049 DESCRIPTION 

5050 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

5051 conflict between the requirements described here and the ISO C standard is unintentional. This I 

5052 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

5053 The bsearch () function searches an array of nel objects, the initial element of which is pointed to 

5054 by base, for an element that matches the object pointed to by key. The size of each element in the 

5055 array is specified by zvidth. 

5056 The comparison function pointed to by compar is called with two arguments that point to the key 

5057 object and to an array element, in that order. 

5058 The application shall ensure that the function returns an integer less than, equal to, or greater I 

5059 than 0 if the key object is considered, respectively, to be less than, to match, or to be greater than I 

5060 the array element. The application shall ensure that the array consists of all the elements that I 

5061 compare less than, all the elements that compare equal to, and all the elements that compare 

5062 greater than the key object, in that order. 

5063 RETURN VALUE 

5064 The bsearch () function shall return a pointer to a matching member of the array, or a null pointer 

5065 if no match is found. If two or more members compare equal, which member is returned is 

5066 unspecified. 

5067 ERRORS 

5068 No errors are defined. 

5069 EXAMPLES 

5070 The example below searches a table containing pointers to nodes consisting of a string and its 

5071 length. The table is ordered alphabetically on the string in the node pointed to by each entry. 

5072 The code fragment below reads in strings and either finds the corresponding node and prints out 

5073 the string and its length, or prints an error message. 

5074 #include <stdio.h> 

5075 #include <stdlib.h> 

5076 #include <string.h> 

5077 #define TABSIZE 1000 

5078 struct node { 

5079 char *string; 

5080 int length; 

5081 }; 

5082 struct node table [TABSIZE] ; 

5083 

5084 

5085 

5086 { 

5087 struct node *node_ptr, node; 

5088 /* routine to compare 2 nodes */ 


/* These are stored in the table. */ 


/* Table to be searched. */ 
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5089 


int node_compare(const void *, const void *); 


5090 


char str_space[20]; /* Space to read string 

into. */ 

5091 




5092 




5093 




5094 


node.string = str_space; 


5095 


while (scant ("%s", node.string) != EOF) { 


5096 


node_ptr = (struct node *)bsearch((void *) 

(&node), 

5097 


(void *)table, TABSIZE, 


5098 


sizeof(struct node), node_compare); 


5099 


if (node_ptr != NULL) { 


5100 


(void)printf("string = %20s, length = 

%d\n", 

5101 


node_ptr->string, node_ptr->length); 

5102 


} else { 


5103 


(void)printf("not found: %s\n", node.string); 

5104 


} 


5105 


} 


5106 

} 



5107 

/* 



5108 


This routine compares two nodes based on an 


5109 


alphabetical ordering of the string field. 


5110 

*/ 



5111 

int 



5112 

node 

:_compare(const void *nodel, const void *node2) 


5113 

{ 



5114 


return strcoll (( (const struct node *)nodel)->string. 

5115 


((const struct node *)node2)->string) ; 


5116 

} 




5117 APPLICATION USAGE 

5118 The pointers to the key and the element at the base of the table should be of type pointer-to- 

5119 element. 

5120 The comparison function need not compare every byte, so arbitrary data may be contained in 

5121 the elements in addition to the values being compared. 

5122 In practice, the array is usually sorted according to the comparison function. 

5123 RATIONALE 

5124 None. 


5125 FUTURE DIRECTIONS 

5126 None. 


5127 SEE ALSO 

5128 hcreate(), lsearch(), qsort (), tsearch(), the System Interface Definitions volume of 

5129 IEEE Std. 1003.1-200x, <stdlib.h> 

5130 CHANGE HISTORY 

5131 First released in Issue 1. 

5132 Derived from Issue 1 of the SVID. 
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5133 Issue 4 

5134 Text indicating the need for various casts is removed from the APPLICATION USAGE section. 

5135 The code in the EXAMPLES section is changed to use strcoll() instead of strcmp () in 

5136 node_compare(). 


5137 

5138 

5139 

5140 

5141 


The return value and the contents of the array are now requirements on the application. 

The DESCRIPTION is changed to specify the order of arguments. 

The following changes are incorporated for alignment with the ISO C standard: 

• The type of arguments key and base, and the type of arguments to compar, are changed from 

void* to const void*. 


5142 

5143 


• The requirement that the table be sorted according to compar is removed from the 
DESCRIPTION. 


5144 Issue 6 

5145 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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5146 NAME 

5147 btowc — single-byte to wide-character conversion 

5148 SYNOPSIS 

5149 #include <stdio.h> 

5150 #include <wchar.h> 

5151 wint_t btowc (int c) ; 

5152 DESCRIPTION 

5153 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

5154 conflict between the requirements described here and the ISO C standard is unintentional. This I 

5155 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

5156 The btozvc () function shall determine whether c constitutes a valid (one-byte) character in the 

5157 initial shift state. 

5158 The behavior of this function shall be affected by the LC_CTYPE category of the current locale. 

5159 RETURN VALUE 

5160 The btozvc () function shall return WEOF if c has the value EOF or if (unsigned char) c does not 

5161 constitute a valid (one-byte) character in the initial shift state. Otherwise, it shall return the 

5162 wide-character representation of that character. 

5163 ERRORS 

5164 No errors are defined. 

5165 EXAMPLES 

5166 None. 

5167 APPLICATION USAGE 

5168 None. 

5169 RATIONALE 

5170 None. 

5171 FUTURE DIRECTIONS 

5172 None. 

5173 SEE ALSO 

5174 zvctob(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

5175 CHANGE HISTORY 

5176 First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 

5177 (E). I 
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5178 NAME 

5179 bzero — memory operations (LEGACY) 

5180 SYNOPSIS 

5181 xsi #include <strings.h> 

5182 void bzero (void *s, size_t n) ; 

5183 

5184 DESCRIPTION 

5185 The bzero () function shall place n zero-valued bytes in the area pointed to by s. 

5186 RETURN VALUE 

5187 The bzero () function shall return no value. 

5188 ERRORS 

5189 No errors are defined. 

5190 EXAMPLES 

5191 None. 

5192 APPLICATION USAGE 

5193 memseti ) is preferred over this function. 

5194 For maximum portability, it is recommended to 

5195 #define bzero (b,len) memset ( (b) , 0, 

5196 RATIONALE 

5197 None. 

5198 FUTURE DIRECTIONS 

5199 This function may be withdrawn in a future version. 

5200 SEE ALSO 

5201 memset( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <strings.h> 

5202 CHANGE HISTORY 

5203 First released in Issue 4, Version 2. 

5204 Issue 5 

5205 Moved from X/OPEN UNIX extension to BASE. 

5206 Issue 6 

5207 This function is marked LEGACY. 


replace the function call to bzero () as follows: 

(size_t)(len)) 
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5208 NAME 

5209 calloc — a memory allocator 

5210 SYNOPSIS 

5211 #include <stdlib.h> 

5212 void *calloc (size_t nelem, size_t elsize) ; 

5213 DESCRIPTION 

5214 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

5215 conflict between the requirements described here and the ISO C standard is unintentional. This I 

5216 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

5217 The calloc () function allocates unused space for an array of nelem elements each of whose size in 

5218 bytes is elsize. The space is initialized to all bits 0. 

5219 The order and contiguity of storage allocated by successive calls to calloc () is unspecified. The 

5220 pointer returned if the allocation succeeds is suitably aligned so that it may be assigned to a 

5221 pointer to any type of object and then used to access such an object or an array of such objects in 

5222 the space allocated (until the space is explicitly freed or reallocated). Each such allocation shall 

5223 yield a pointer to an object disjoint from any other object. The pointer returned points to the start 

5224 (lowest byte address) of the allocated space. If the space cannot be allocated, a null pointer is 

5225 returned. If the size of the space requested is 0, the behavior is implementation-dependent; the 

5226 value returned shall be either a null pointer or a unique pointer. 

5227 RETURN VALUE 

5228 Upon successful completion with both nelem and elsize non-zero, calloc () shall return a pointer to 

5229 the allocated space. If either nelem or elsize is 0, then either a null pointer or a unique pointer 

5230 value that can be successfully passed to free( ) shall be returned. Otherwise, it shall return a null 

5231 cx pointer and set errno to indicate the error. 

5232 ERRORS 

5233 The calloc () function shall fail if: 

5234 cx [ENOMEM] Insufficient memory is available. 

5235 EXAMPLES 

5236 None. 

5237 APPLICATION USAGE 

5238 There is now no requirement for the implementation to support the inclusion of <malloc.h>. 

5239 RATIONALE 

5240 None. 

5241 FUTURE DIRECTIONS 

5242 None. 

5243 SEE ALSO 

5244 free(), malloc(), realloc(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

5245 <stdlib.h> 

5246 CHANGE HISTORY 

5247 First released in Issue 1. 

5248 Derived from Issue 1 of the SVID. 
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5249 Issue 4 


5262 Issue 6 


The setting of errno and the [ENOMEM] error are marked as extensions. 

The APPLICATION USAGE section is changed to record that <malloc.h> need no longer be 
supported on XSI-conformant systems. 

The following changes are incorporated in this issue for alignment with the ISO C standard: 

• The DESCRIPTION is updated to indicate: 

— The order and contiguity of storage allocated by successive calls to this function is 
unspecified. 

— Each allocation yields a pointer to an object disjoint from any other object. 

— The returned pointer points to the lowest byte address of the allocation. 

— The behavior if space is requested of zero size. 

• The RETURN VALUE section is updated to indicate what is returned if either nelem or elsize 
is 0. 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The setting of errno and the [ENOMEM] error condition are mandatory if an insufficient 
memory condition occurs. 
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5268 NAME 

5269 catclose — close a message catalog descriptor 

5270 SYNOPSIS 

5271 xsi tinclude <nl_types.h> 

5272 int catclose (nl_catd catd) ; 

5273 

5274 DESCRIPTION 

5275 The catclose () function shall close the message catalog identified by catd. If a file descriptor is 

5276 used to implement the type nl_catd, that file descriptor shall be closed. 

5277 RETURN VALUE 

5278 Upon successful completion, catclose() shall return 0; otherwise, -1 shall be returned, and errno 

5279 set to indicate the error. 

5280 ERRORS 

5281 The catclose () function may fail if: 

5282 [EBADF] The catalog descriptor is not valid. 

5283 [EINTR] The catclose ( ) function was interrupted by a signal. 

5284 EXAMPLES 

5285 None. 

5286 APPLICATION USAGE 

5287 None. 

5288 RATIONALE 

5289 None. 

5290 FUTURE DIRECTIONS 

5291 None. 

5292 SEE ALSO 

5293 catgets(), catopen(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

5294 <nl_types.h> 

5295 CHANGE HISTORY 

5296 First released in Issue 2. 

5297 Issue 4 

5298 The [EBADF] and [EINTR] errors are added to the ERRORS section. 


166 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


catgetsO 


5299 NAME 

5300 catgets — read a program message 

5301 SYNOPSIS 

5302 xsi tinclude <nl_types.h> 

5303 char *catgets (nl_catd catd, int s et_id, int msg_id, const char *s) ; 

5304 

5305 DESCRIPTION 

5306 The catgets() function attempts to read message msg_id, in set set_id, from the message catalog 

5307 identified by catd. The catd argument is a message catalog descriptor returned from an earlier 

5308 call to catopenO • The s argument points to a default message string which shall be returned by 

5309 catgets () if it cannot retrieve the identified message. 

5310 The catgets () function need not be reentrant. A function that is not required to be reentrant is not 

5311 required to be thread-safe. 

5312 RETURN VALUE 

5313 If the identified message is retrieved successfully, catgets () shall return a pointer to an internal 

5314 buffer area containing the null-terminated message string. If the call is unsuccessful for any 

5315 reason, s shall be returned and errno may be set to indicate the error. 

5316 ERRORS 

5317 The catgets () function may fail if: 

5318 [EBADF] 

5319 [EINTR] 

5320 

5321 [EINVAL] 

5322 [ENOMSG] 

5323 EXAMPLES 

5324 None. 

5325 APPLICATION USAGE 

5326 None. 

5327 RATIONALE 

5328 None. 

5329 FUTURE DIRECTIONS 

5330 None. 

5331 SEE ALSO 

5332 catcloseO , catopenO , the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

5333 <nl_types.h> 

5334 CHANGE HISTORY 

5335 First released in Issue 2. 

5336 Issue 4 

5337 The type of argument s is changed from char* to const char*. 

5338 The [EBADF] and [EINTR] errors are added to the ERRORS section. 


The catd argument is not a valid message catalog descriptor open for reading. 

The read operation was terminated due to the receipt of a signal, and no data 
was transferred. 

The message catalog identified by catd is corrupted. 

The message identified by set_id and msg_id is not in the message catalog. 
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5339 Issue 4, Version 2 

5340 The following changes are incorporated for X/OPEN UNIX conformance: 

5341 • The RETURN VALUE section notes that errno may be set to indicate an error. 

5342 • In the ERRORS section, [EINVAL] and [ENOMSG] are added as optional errors. 

5343 Issue 5 

5344 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 

5345 Issue 6 

5346 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 


168 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


catopenO 


5347 NAME 

5348 catopen — open a message catalog 

5349 SYNOPSIS 

5350 xsi #include <nl_types.h> 

5351 nl_catd catopen (const char *name, int oflag) ; 

5352 

5353 DESCRIPTION 

5354 The catopen () function shall open a message catalog and return a message catalog descriptor. 

5355 The name argument specifies the name of the message catalog to be opened. If name contains a 

5356 ' /', then name specifies a complete name for the message catalog. Otherwise, the environment 

5357 variable NLSPATH is used with name substituted for %N (see the System Interface Definitions I 

5358 volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables). If NLSPATH does not exist I 

5359 in the environment, or if a message catalog cannot be found in any of the components specified 

5360 by NLSPATH, then an implementation-dependent default path is used. This default may be 

5361 affected by the setting of LC_MESSAGES if the value of oflag is NL_CAT_LOCALE, or the LANG 

5362 environment variable if oflag is 0. 

5363 A message catalog descriptor remains valid in a process until that process closes it, or a 

5364 successful call to one of the exec functions. A change in the setting of the LC_MESSAGES 

5365 category may invalidate existing open catalogs. 

5366 If a file descriptor is used to implement message catalog descriptors, the FD_CLOEXEC flag 

5367 shall be set; see <fcntl.h>. 

5368 If the value of the oflag argument is 0, the LANG environment variable is used to locate the 

5369 catalog without regard to the LC_MESSAGES category. If the oflag argument is 

5370 NL_CAT_LOCALE, the LC_MESSAGES category is used to locate the message catalog (see the I 

5371 System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 8.2, Internationalization I 

5372 Variables). I 

5373 RETURN VALUE 

5374 Upon successful completion, catopen () shall return a message catalog descriptor for use on 

5375 subsequent calls to catgets () and catclose( ). Otherwise, catopen () shall return (nl_catd) -1 and set 

5376 errno to indicate the error. 


5377 ERRORS 

5378 The catopen () function may fail if: 

5379 [EACCES] Search permission is denied for the component of the path prefix of the 

5380 message catalog or read permission is denied for the message catalog. 

5381 [EMFILE] |OPEN_MAX} file descriptors are currently open in the calling process. 

5382 [ENAMETOOLONG] 

5383 The length of the path name of the message catalog exceeds {PATH_MAX}, or 

5384 a path name component is longer than {NAME_MAX}. 


5385 

5386 

5387 


[ENAMETOOLONG] 

Path name resolution of a symbolic link produced an intermediate result 
whose length exceeds {PATH_MAX[. 


5388 


[ENFILE] 


Too many files are currently open in the system. 


5389 [ENOENT] The message catalog does not exist or the name argument points to an empty 

5390 string. 
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5391 [ENOMEM] Insufficient storage space is available. 

5392 [ENOTDIR] A component of the path prefix of the message catalog is not a directory. 

5393 EXAMPLES 

5394 None. 

5395 APPLICATION USAGE 

5396 Some implementations of catopen() use malloc() to allocate space for internal buffer areas. The 

5397 catopen () function may fail if there is insufficient storage space available to accommodate these 

5398 buffers. 

5399 Portable applications must assume that message catalog descriptors are not valid after a call to 

5400 one of the exec functions. 

5401 Application writers should be aware that guidelines for the location of message catalogs have 

5402 not yet been developed. Therefore they should take care to avoid conflicting with catalogs used 

5403 by other applications and the standard utilities. 

5404 RATIONALE 

5405 None. 

5406 FUTURE DIRECTIONS 

5407 None. 

5408 SEE ALSO 

5409 catclose (), catgets (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <fcntl.h>, 

5410 <nl_types.il>, the Commands and Utilities volume of IEEE Std. 1003.1-200x 

5411 CHANGE HISTORY 

5412 First released in Issue 2. 

5413 Issue 4 

5414 The type of argument name is changed from char* to const char*. 

5415 The DESCRIPTION is updated: 

5416 • To indicate the longevity of message catalog descriptors. 

5417 • To specify values for the oflag argument and the effect of LC_MESSAGES and NLSPATH. 

5418 The [EACCES], [EMFILE], [ENAMETOOLONG], [ENFILE], [ENOENT], and [ENOTDIR] errors 

5419 are added to the ERRORS section. 

5420 The APPLICATION USAGE section is updated to indicate: 

5421 • Portable applications should not assume the continued validity of message catalog 

5422 descriptors after a call to one of the exec functions. 

5423 • Message catalogs must be located with care. 

5424 Issue 4, Version 2 

5425 The following change is incorporated for X/OPEN UNIX conformance: 

5426 • In the ERRORS section, an [ENAMETOOLONG] condition is defined that may report 

5427 excessive length of an intermediate result of path name resolution of a symbolic link. 
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5428 NAME 

5429 cbrt — cube root function 

5430 SYNOPSIS 

5431 xsi tinclude <math.h> 

5432 double cbrt (double x) ; 

5433 

5434 DESCRIPTION 

5435 The cbrt( ) function computes the cube root of x. 

5436 RETURN VALUE 

5437 Upon successful completion, cbrt( ) shall return the cube root of x. If x is NaN, cbrt( ) shall return 

5438 NaN and errno may be set to [EDOM]. 

5439 ERRORS 

5440 The cbrt( ) function may fail if: 

5441 [EDOM] The value of x is NaN. 

5442 EXAMPLES 

5443 None. 

5444 APPLICATION USAGE 

5445 None. 

5446 RATIONALE 

5447 None. 

5448 FUTURE DIRECTIONS 

5449 None. 

5450 SEE ALSO 

5451 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

5452 CHANGE HISTORY 

5453 First released in Issue 4, Version 2. 

5454 Issue 5 

5455 Moved from X/OPEN UNIX extension to BASE. 
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5456 NAME 

5457 ceil — ceiling value function 

5458 SYNOPSIS 

5459 #include <math.h> 

5460 double ceil (double x) ; 

5461 DESCRIPTION 

5462 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

5463 conflict between the requirements described here and the ISO C standard is unintentional. This I 

5464 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

5465 The ceil () function shall compute the smallest integral value not less than x. 

5466 An application wishing to check for error situations should set errno to 0 before calling ceil(). If 

5467 errno is non-zero on return, or the return value is NaN, an error has occurred. 

5468 RETURN VALUE 

5469 Upon successful completion, ceil() shall return the smallest integral value not less than x, 

5470 expressed as a type double. 

5471 xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

5472 If the correct value would cause overflow, HUGE_VAL shall be returned and errno set to 

5473 xsi [ERANGE], If x is ±Inf or ±0, the value of x shall be returned. 

5474 ERRORS 

5475 The ceil () function shall fail if: 

5476 [ERANGE] The result overflows. 

5477 The ceil () function may fail if: 

5478 xsi [EDOM] The value of x is NaN. 

5479 xsi No other errors shall occur. 

5480 EXAMPLES 

5481 None. 

5482 APPLICATION USAGE 

5483 The integral value returned by ceil () as a double need not be expressible as an int or long int. 

5484 The return value should be tested before assigning it to an integer type to avoid the undefined 

5485 results of an integer overflow. 

5486 The ceil() function can only overflow when the floating point representation has 

5487 DBL_MANT_DIG > DBL_MAX_EXP. 

5488 RATIONALE 

5489 None. 

5490 FUTURE DIRECTIONS 

5491 None. 

5492 SEE ALSO 

5493 floor (), isnan (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

5494 CHANGE HISTORY 

5495 First released in Issue 1. 

5496 Derived from Issue 1 of the SVID. 


172 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


ceil() 


5497 Issue 4 

5498 References to matherr () are removed. 

5499 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

5500 ISO C standard and to rationalize error handling in the mathematics functions. 

5501 The return value specified for [EDOM] is marked as an extension. 

5502 Support for x being ±Inf or ±0 is added to the RETURN VALUE section and marked as an 

5503 extension. 

5504 Issue 5 

5505 The DESCRIPTION is updated to indicate how an application should check for an error. This 

5506 text was previously published in the APPLICATION USAGE section. 
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5507 NAME 

5508 cfgetispeed — get input baud rate 

5509 SYNOPSIS 

5510 tinclude <termios.h> 

5511 speed_t cfgetispeed(const struct termios *termios_p) ; 

5512 DESCRIPTION 

5513 The cfgetispeed () function shall extract the input baud rate from the termios structure to which 

5514 the termios_p argument points. 

5515 This function shall return exactly the value in the termios data structure, without interpretation. 

5516 RETURN VALUE 

5517 Upon successful completion, cfgetispeed () shall return a value of type speed_t representing the 

5518 input baud rate. 

5519 ERRORS 

5520 No errors are defined. 

5521 EXAMPLES 

5522 None. 

5523 APPLICATION USAGE 

5524 None. 

5525 RATIONALE 

5526 The term band is used historically here, but is not technically correct. This is properly "bits per 

5527 second", which may not be the same as baud. However, the term is used because of the 

5528 historical usage and understanding. 

5529 The cfgetospeed(), cfgetispeed (), cfsetospeed( ), and cfsetispeed( ) functions do not take arguments as 

5530 numbers, but rather as symbolic names. There are two reasons for this: 

5531 1. Historically, numbers were not used because of the way the rate was stored in the data 

5532 structure. This is retained even though a function is now used. 

5533 2. More importantly, only a limited set of possible rates is at all portable, and this constrains 

5534 the application to that set. 

5535 There is nothing to prevent an implementation to accept, as an extension, a number (such as 126) 

5536 if it wished, and because the encoding of the Bxxx symbols is not specified, this can be done so 

5537 no ambiguity is introduced. 

5538 Setting the input baud rate to zero was a mechanism to allow for split baud rates. Clarifications 

5539 in this volume of IEEE Std. 1003.1-200x have made it possible to determine whether split rates 

5540 are supported and to support them without having to treat zero as a special case. Since this 

5541 functionality is also confusing, it has been declared obsolescent. The 0 argument referred to is 

5542 the literal constant 0, not the symbolic constant B0. This volume of IEEE Std. 1003.1-200x does 

5543 not preclude B0 from being defined as the value 0; in fact, implementations would likely benefit 

5544 from the two being equivalent. This volume of IEEE Std. 1003.1-200x does not fully specify 

5545 whether the previous cfsetispeed() value is retained after a tcgetattr{) as the actual value or as 

5546 zero. Therefore, portable applications should always set both the input speed and output speed 

5547 when setting either. 

5548 In historical implementations, the baud rate information is traditionally kept in c_cflag. 

5549 Applications should be written to presume that this might be the case (and thus not blindly copy 

5550 c_cflag), but not to rely on it in case it is in some other field of the structure. Setting the c_cflag 

5551 field absolutely after setting a baud rate is a non-portable action because of this. In general, the 
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5552 unused parts of the flag fields might be used by the implementation and should not be blindly 

5553 copied from the descriptions of one terminal device to another. 

5554 FUTURE DIRECTIONS 

5555 None. 

5556 SEE ALSO 

5557 cfgetospeed(), cfsetispeed(), cfsetospeed(), tcgetattr(), the System Interface Definitions volume of 

5558 IEEE Std. 1003.1-200x, <termios.h>, the System Interface Definitions volume of I 

5559 IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface I 

5560 CHANGE HISTORY 

5561 First released in Issue 3. 

5562 Entry included for alignment with the POSIX.1-1988 standard. 

5563 Issue 4 

5564 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

5565 • The type of the argument termiosjp is changed from struct termios* to const struct termios*. 

5566 • The DESCRIPTION is changed to indicate that the function simply returns the value from 

5567 termiosjp, irrespective of how that structure was obtained. Issue 3 states that if terviiosjp was 

5568 not obtained by a successful call to tcgetattr( ), the behavior is undefined. 
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5569 NAME 

5570 cfgetospeed — get output baud rate 

5571 SYNOPSIS 

5572 #include <termios.h> 

5573 speed_t cfgetospeed(const struct termios *termios_p) ; 

5574 DESCRIPTION 

5575 The cfgetospeed () function shall extract the output baud rate from the termios structure to which 

5576 the termios_p argument points. 

5577 This function shall return exactly the value in the termios data structure, without interpretation. 

5578 RETURN VALUE 

5579 Upon successful completion, cfgetospeed () shall return a value of type speed_t representing the 

5580 output baud rate. 

5581 ERRORS 

5582 No errors are defined. 

5583 EXAMPLES 

5584 None. 

5585 APPLICATION USAGE 

5586 None. 

5587 RATIONALE 

5588 Refer to cfgetispeed (). 

5589 FUTURE DIRECTIONS 

5590 None. 

5591 SEE ALSO 

5592 cfgetispeed (), cfsetispeed{), cfsetospeed(), tcgetattr{), the System Interface Definitions volume of 

5593 IEEE Std. 1003.1-200x, <termios.h>, the System Interface Definitions volume of I 

5594 IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface I 

5595 CHANGE HISTORY 

5596 First released in Issue 3. 

5597 Entry included for alignment with the POSIX.1-1988 standard. 

5598 Issue 4 

5599 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

5600 • The type of the argument termios_p is changed from struct termios* to const struct termios*. 

5601 • The DESCRIPTION is changed to indicate that the function simply returns the value from 

5602 termiosjp, irrespective of how that structure was obtained. Issue 3 states that if terviiosjp was 

5603 not obtained by a successful call to tcgetattr( ), the behavior is undefined. 
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5604 NAME 

5605 cfsetispeed — set input baud rate 

5606 SYNOPSIS 

5607 #include <termios.h> 

5608 int cfsetispeed(struct termios *termios_p, speed_t speed); 

5609 DESCRIPTION 

5610 The cfsetispeed() function shall set the input baud rate stored in the structure pointed to by 

5611 termios_p to speed. 

5612 There shall be no effect on the baud rates set in the hardware until a subsequent successful call 

5613 to tcsetattrO with the same termios structure. Similarly, errors resulting from attempts to set I 

5614 baud rates not supported by the terminal device need not be detected until the tcsetattrO I 

5615 function is called. I 

5616 RETURN VALUE 

5617 man Upon successful completion, cfsetispeedO shall return 0; otherwise, -1 shall be returned, and 

5618 errno may be set to indicate the error. 

5619 ERRORS 

5620 The cfsetispeed () function may fail if: 

5621 man [EINVAL] The speed value is not a valid baud rate. 

5622 man [EINVAL] The value of speed is outside the range of possible speed values as specified in 

5623 <termios.h>. 

5624 EXAMPLES 

5625 None. 

5626 APPLICATION USAGE 

5627 None. 

5628 RATIONALE 

5629 Refer to cfgetispeed (). 

5630 FUTURE DIRECTIONS 

5631 None. 

5632 SEE ALSO 

5633 cfgetispeed0, cfgetospeedO, cfsetospeedO, tcsetattrO , the System Interface Definitions volume of 

5634 IEEE Std. 1003.1-200x, <termios.h>, the System Interface Definitions volume of I 

5635 IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface I 

5636 CHANGE HISTORY 

5637 First released in Issue 3. 

5638 Entry included for alignment with the POSIX.1-1988 standard. 

5639 Issue 4 

5640 The first description of the [EINVAL] error is added and is marked as an extension. 

5641 Issue 4, Version 2 

5642 The ERRORS section is changed to indicate that [EINVAL] may be returned if the specified 

5643 speed is outside the range of possible speed values given in <termios.h>. 
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5644 

5645 

5646 

5647 


Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The optional setting of errno and the [EINVAL] error conditions are added. 
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5648 NAME 

5649 cfsetospeed — set output baud rate 

5650 SYNOPSIS 

5651 #include <termios.h> 

5652 int cfsetospeed(struct termios *termios_p, speed_t speed); 

5653 DESCRIPTION 

5654 The cfsetospeed() function shall set the output baud rate stored in the structure pointed to by 

5655 termios_p to speed . 

5656 There shall be no effect on the baud rates set in the hardware until a subsequent successful call 

5657 to tcsetattrO with the same termios structure. Similarly, errors resulting from attempts to set I 

5658 baud rates not supported by the terminal device need not be detected until the tcsetattrO I 

5659 function is called. I 

5660 RETURN VALUE 

5661 man Upon successful completion, cfsetospeedO shall return 0; otherwise, it shall return -1 and errno 

5662 may be set to indicate the error. 

5663 ERRORS 

5664 The cfsetospeed () function may fail if: 

5665 man [EINVAL] The speed value is not a valid baud rate. 

5666 man [EINVAL] The value of speed is outside the range of possible speed values as specified in 

5667 <termios.h>. 

5668 EXAMPLES 

5669 None. 

5670 APPLICATION USAGE 

5671 None. 

5672 RATIONALE 

5673 Refer to cfgetispeed (). 

5674 FUTURE DIRECTIONS 

5675 None. 

5676 SEE ALSO 

5677 cfgetispeed0, cfgetospeedO, cfsetispeedO, tcsetattrO, the System Interface Definitions volume of 

5678 IEEE Std. 1003.1-200x, <termios.h>, the System Interface Definitions volume of I 

5679 IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface I 

5680 CHANGE HISTORY 

5681 First released in Issue 3. 

5682 Entry included for alignment with the POSIX.1-1988 standard. 

5683 Issue 4 

5684 The first description of the [EINVAL] error is added and is marked as an extension. 

5685 Issue 4, Version 2 

5686 The ERRORS section is changed to indicate that [EINVAL] may be returned if the specified 

5687 speed is outside the range of possible speed values given in <termios.h>. 
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5688 

5689 

5690 

5691 


Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The optional setting of errno and the [EINVAL] error conditions are added. 
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5692 NAME 

5693 chdir — change working directory 

5694 SYNOPSIS 

5695 tinclude <unistd.h> 


5696 int chdir (const char *path); 


5697 DESCRIPTION 

5698 The chdir () function shall cause the directory named by the path name pointed to by the path 

5699 argument to become the current working directory; that is, the starting point for path searches 

5700 for path names not beginning with ' / ' ■ 

5701 RETURN VALUE 

5702 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned, the current 

5703 working directory shall remain unchanged, and errno shall be set to indicate the error. 

5704 ERRORS 

5705 The chdir () function shall fail if: 


5706 


[EACCES] 


Search permission is denied for any component of the path name. 


5707 Notes to Reviewers 

5708 This section with side shading will not appear in the final copy. - Ed. 


5709 


Do we need to reconcile the [ELOOP] errors? 


5710 MAN [ELOOP] 

5711 


A loop exists in symbolic links encountered during resolution of the path 
argument. 


5712 

5713 

5714 

5715 


[ENAMETOOLONG] 

The path argument exceeds |PATH_MAX[ in length or a path name 
component is longer than {NAME_MAX} while _POSIX_NO_TRUNC is in 
effect. 


5716 

5717 


[ENOENT] A component of path does not name an existing directory or path is an empty 

string. 


5718 


[ENOTDIR] A component of the path name is not a directory. 


5719 


The chdir () function may fail if: 


5720 [ELOOP] More than [SYMLOOP_MAX[ symbolic links were encountered during I 

5721 resolution of the path argument. I 

5722 MAN [ENAMETOOLONG] 

5723 As a result of encountering a symbolic link in resolution of the path argument, I 

5724 the length of the substituted path name string exceeded [PATH_MAX[. I 

5725 EXAMPLES 


[ENAMETOOLONG] 

As a result of encountering a symbolic link in resolution of the path argument, 
the length of the substituted path name string exceeded [PATH_MAX[. 
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5726 Changing the Current Working Directory 

5727 The following example makes the value pointed to by directory, /tmp, the current working 

5728 directory. 

5729 #include <unistd.h> 

5730 

5731 char *directory = "/tmp"; 

5732 int ret; 

5733 ret = chdir (directory) ; 

5734 APPLICATION USAGE 

5735 The chdir() function only affects the working directory of the current process. The result if a 

5736 NULL argument is passed to chdir () is unspecified because some implementations dynamically 

5737 allocate space in that case. 

5738 RATIONALE 

5739 The chdir( ) function only affects the working directory of the current process. 

5740 The result if a NULL argument is passed to chdir () is left implementation-dependent because 

5741 some implementations dynamically allocate space in that case. 

5742 FUTURE DIRECTIONS 

5743 None. 

5744 SEE ALSO 

5745 getcwd( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

5746 CHANGE HISTORY 

5747 First released in Issue 1. 

5748 Derived from Issue 1 of the SVID. 

5749 Issue 4 

5750 The <unistd.h> header is added to the SYNOPSIS section. 

5751 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

5752 • The type of argument path is changed from char* to const char*. 

5753 The following change is incorporated for alignment with the FIPS requirements: 

5754 • In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 

5755 name component is larger that |NAME_MAX} is now defined as mandatory and marked as 

5756 an extension. 

5757 Issue 4, Version 2 

5758 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 

5759 • It states that [ELOOP] is returned if too many symbolic links are encountered during path 

5760 name resolution. 

5761 • A second [ENAMETOOLONG] condition is defined that may report excessive length of an 

5762 intermediate result of path name resolution of a symbolic link. 

5763 Issue 6 

5764 The APPLICATION USAGE section is added. 

5765 The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

5766 • The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 

5767 This is since behavior may vary from one file system to another. 
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5768 The following new requirements on POSIX implementations derive from alignment with the 

5769 Single UNIX Specification: 

5770 • The [ELOOP] mandatory error condition is added. 

5771 • A second [ENAMETOOLONG] is added as an optional error condition. 

5772 The following changes were made to align with the IEEE P1003.1a draft standard: 

5773 • The [ELOOP] optional error condition is added. 
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5774 NAME 

5775 chmod — change mode of a file 

5776 SYNOPSIS 

5777 #include <sys/stat.h> 

5778 int chmod (const char *path, mode_t mode); 

5779 DESCRIPTION 

5780 xsi The chmod () function shall change S_ISUID, S_ISGID, S_ISVTX,and the file permission bits of 

5781 the file named by the path name pointed to by the path argument to the corresponding bits in the 

5782 mode argument. The application shall ensure that the effective user ID of the process matches the I 

5783 owner of the file or the process has appropriate privileges in order to do this. I 

5784 S_ISUID, S_ISGID, and the file permission bits are described in <sys/stat.h>. 

5785 xsi If a directory is writable and the mode bit S_ISVTX is set on the directory, a process may remove 

5786 or rename files within that directory only if one or more of the following is true: 

5787 • The effective user ID of the process is the same as that of the owner ID of the file. 

5788 • The effective user ID of the process is the same as that of the owner ID of the directory. 

5789 • The process has appropriate privileges. 

5790 

5791 Notes to Reviewers 

5792 This section with side shading will not appear in the final copy. - Ed. 

5793 Dl, XSH, ERN 79, HP A will generate a definition of S_ISVTX for XBD. 

5794 xsi If the S_ISVTX bit is set on a non-directory file, the behavior is unspecified. 

5795 If the calling process does not have appropriate privileges, and if the group ID of the file does 

5796 not match the effective group ID or one of the supplementary group IDs and if the file is a 

5797 regular file, bit S_ISGID (set-group-ID on execution) in the file's mode shall be cleared upon 

5798 successful return from chmod (). 

5799 Additional implementation-dependent restrictions may cause the S_ISUID and S_ISGID bits in 

5800 mode to be ignored. 

5801 The effect on file descriptors for files open at the time of a call to chmod() is implementation- 

5802 dependent. 

5803 Upon successful completion, chmod () shall mark for update the st_ctime field of the file. 

5804 RETURN VALUE 

5805 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 

5806 indicate the error. If -1 is returned, no change to the file mode occurs. 

5807 ERRORS 

5808 The chmod( ) function shall fail if: 

5809 [EACCES] Search permission is denied on a component of the path prefix. 

5810 man [ELOOP] A loop exists in symbolic links encountered during resolution of the path I 

5811 argument. I 

5812 [ENAMETOOLONG] I 

5813 The length of the path argument exceeds |PATH_MAX} or a path name 

5814 component is longer than |NAME_MAX} while _POSIX_NO_TRUNC is in 
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5815 effect. 

5816 [ENOTDIR] A component of the path prefix is not a directory. 

5817 [ENOENT] A component of path does not name an existing file or path is an empty string. 

5818 [EPERM] The effective user ID does not match the owner of the file and the process 

5819 does not have appropriate privileges. 

5820 [EROFS] The named file resides on a read-only file system. 

5821 The chmod () function may fail if: 

5822 man [EINTR] A signal was caught during execution of the function. 

5823 man [EINVAL] The value of the mode argument is invalid. I 

5824 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during I 

5825 resolution of the path argument. I 

5826 man [ENAMETOOLONG] 

5827 As a result of encountering a symbolic link in resolution of the path argument, I 

5828 the length of the substituted path name strings exceeded {PATH_MAX}. I 

5829 EXAMPLES 

5830 Setting Read Permissions for User, Group, and Others 

5831 The following example sets read permissions for the owner, group, and others. 

5832 #include <sys/stat.h> 

5833 const char *path; 

5834 

5835 chmod (path, S_IRUSR | S_IRGRP | S_IROTH) ; 

5836 Setting Read, Write, and Execute Permissions for the Owner Only 

5837 The following example sets read, write, and execute permissions for the owner, and no 

5838 permissions for group and others. 

5839 #include <sys/stat.h> 

5840 const char *path; 

5841 

5842 chmod (path, S_IRWXU) ; 

5843 Setting Different Permissions for Owner, Group, and Other 

5844 The following example sets owner permissions for CHANGEFILE to read, write, and execute, 

5845 group permissions to read and execute, and other permissions to read. 

5846 #include <sys/stat.h> 

5847 #define CHANGEFILE "/etc/myfile" 

5848 

5849 chmod(CHANGEFILE, S_IRWXU|S_IRGRP|S_IXGRP|S_IROTH); 


[ENAMETOOLONG] 

As a result of encountering a symbolic link in resolution of the path argument, 
the length of the substituted path name strings exceeded {PATH_MAX}. 
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5850 Setting and Checking File Permissions 

5851 The following example sets the file permission bits for a file named /home/cnd/modl, then calls 

5852 the stat () function to verify the permissions. 

5853 #include <sys/types . h> 

5854 #include <sys/stat.h> 

5855 int status; 

5856 struct stat buffer 

5857 

5858 chmod("home/cnd/modl", S_IRWXU|S_IRWXG|S_IROTH|S_IWOTH); 

5859 status = stat ( "home/cnd/modl " , Sbuffer; ) ; 

5860 APPLICATION USAGE 

5861 In order to ensure that the S_ISUID and S_ISGID bits are set, an application requiring this should 

5862 use stat( ) after a successful chmod() to verify this. 

5863 Any file descriptors currently open by any process on the file may become invalid if the mode of 

5864 the file is changed to a value which would deny access to that process. One situation where this 

5865 could occur is on a stateless file system. 

5866 RATIONALE 

5867 This volume of IEEE Std. 1003.1-200x specifies that the S_ISGID bit is cleared by chmod() on a 

5868 regular file under certain conditions. This is specified on the assumption that regular files may 

5869 be executed, and the system should prevent users from making executable setgid( ) files perform 

5870 with privileges that the caller does not have. On implementations that support execution of 

5871 other file types, the S_ISGID bit should be cleared for those file types under the same 

5872 circumstances. 

5873 Implementations that use the S_ISUID bit to indicate some other function (for example, 

5874 mandatory record locking) on non-executable files need not clear this bit on writing. They 

5875 should clear the bit for executable files and any other cases where the bit grants special powers 

5876 to processes that change the file contents. Similar comments apply to the S_ISGID bit. 

5877 FUTURE DIRECTIONS 

5878 None. 

5879 SEE ALSO 

5880 chozvn(), mkdir(), mkfifo(), open(), stat(), statvfs(), the System Interface Definitions volume of 

5881 IEEE Std. 1003.1-200x, <sys/stat.h>, <sys/types.h> 

5882 CHANGE HISTORY 

5883 First released in Issue 1. 

5884 Derived from Issue 1 of the SVID. 

5885 Issue 4 

5886 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

5887 XSI-conformant systems. 

5888 The [EINVAL] error is marked as an extension. 

5889 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

5890 • The type of argument path is changed from char* to const char*. 

5891 The following change is incorporated for alignment with the FIPS requirements: 

5892 • In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 

5893 name component is larger that |NAME_MAX} is now defined as mandatory and marked as 
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5894 an extension. 

5895 Issue 4, Version 2 

5896 The following changes are incorporated for X/OPEN UNIX conformance: 

5897 • The DESCRIPTION is updated to describe X/OPEN UNIX functionality relating to 

5898 permission checks applied when removing or renaming files in a directory having the 

5899 S_ISVTX bit set. 

5900 • In the ERRORS section, the condition whereby [ELOOP] is returned if too many symbolic 

5901 links are encountered during path name resolution is defined as mandatory, and [EINTR] is 

5902 added as an optional error. 

5903 • In the ERRORS section, a second [ENAMETOOLONG] condition is defined that may report 

5904 excessive length of an intermediate result of path name resolution of a symbolic link. 

5905 Issue 6 

5906 The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

5907 • The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 

5908 This is since behavior may vary from one file system to another. 

5909 The following new requirements on POSIX implementations derive from alignment with the 

5910 Single UNIX Specification: 

5911 • The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 

5912 required for conforming implementations of previous POSIX specifications, it was not 

5913 required for UNIX applications. 

5914 • The [EINVAL] and [EINTR] optional error conditions are added. 

5915 • A second [ENAMETOOLONG] is added as an optional error condition. 

5916 The following changes were made to align with the IEEE P1003.1a draft standard: 

5917 • The [ELOOP] optional error condition is added. 

5918 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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5919 NAME 

5920 chown — change owner and group of a file 

5921 SYNOPSIS 

5922 #include <unistd.h> 


5923 


int chown(const char *path, uid_t owner, gid_t group)} 


5924 DESCRIPTION 

5925 The path argument points to a path name naming a file. The user ID and group ID of the named 

5926 file are set to the numeric values contained in owner and group, respectively. 

5927 Only processes with an effective user ID equal to the user ID of the file or with appropriate 

5928 privileges may change the ownership of a file. If _POSIX_CHOWN_RESTRICTED is in effect for 

5929 path : 

5930 • Changing the user ID is restricted to processes with appropriate privileges. 

5931 • Changing the group ID is permitted to a process with an effective user ID equal to the user 

5932 ID of the file, but without appropriate privileges, if and only if owner is equal to the file's user 

5933 ID or (uid_t)-l and group is equal either to the calling process' effective group ID or to one of 

5934 its supplementary group IDs. 

5935 If the specified file is a regular file, one or more of the S_IXUSR, S_IXGRP, or S_IXOTH bits of 

5936 the file mode are set, and the process does not have appropriate privileges, the set-user-ID 

5937 (S_ISUID) and set-group-ID (S_ISGID) bits of the file mode shall be cleared upon successful 

5938 return from chown (). If the specified file is a regular file, one or more of the S_IXUSR, S_IXGRP, 

5939 or S_IXOTH bits of the file mode are set, and the process has appropriate privileges, it is 

5940 implementation-dependent whether the set-user-ID and set-group-ID bits are altered. If the 

5941 chown () function is successfully invoked on a file that is not a regular file and one or more of the 

5942 S_IXUSR, S_IXGRP, or S_IXOTH bits of the file mode are set, the set-user-ID and set-group-ID 

5943 bits may be cleared. 

5944 If owner or group is specified as (uid_t)-l or (gid_t)-l, respectively, the corresponding ID of the 

5945 file is unchanged. 

5946 Upon successful completion, clwzvn () shall mark for update the stjctime field of the file. 

5947 RETURN VALUE 

5948 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 

5949 indicate the error. If -1 is returned, no changes are made in the user ID and group ID of the file. 

5950 ERRORS 

5951 The clwzvn () function shall fail if: 


5952 

5953 

5954 


[EACCES] Search permission is denied on a component of the path prefix. 

[ELOOP] A loop exists in symbolic links encountered during resolution of the path I 

argument. I 


5955 

5956 

5957 

5958 


[ENAMETOOLONG] 

The length of the path argument exceeds |PATH_MAX} or a path name 
component is longer than {NAME_MAX} while _POSIX_NO_TRUNC is in 
effect. 


5959 

5960 

5961 

5962 


[ENOTDIR] 

[ENOENT] 

[EPERM] 


A component of the path prefix is not a directory. 

A component of path does not name an existing file or path is an empty string. 

The effective user ID does not match the owner of the file, or the calling 
process does not have appropriate privileges and 
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5963 

5964 

5965 

5966 

5967 

5968 

5969 

5970 

5971 


_POSIX_CHOWN_RESTRICTED indicates that such privilege is required. 
[EROFS] The named file resides on a read-only file system. 

The chown () function may fail if: 

[EIO] An I/O error occurred while reading or writing to the file system. 

[EINTR] The chown () function was interrupted by a signal which was caught. 

[EINVAL] The owner or group ID supplied is not a value supported by the 

implementation. 

[ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 

resolution of the path argument. 


5972 [ENAMETOOLONG] 

5973 As a result of encountering a symbolic link in resolution of the path argument, I 

5974 the length of the substituted path name string exceeded {PATH_MAX}. I 

5975 EXAMPLES 

5976 None. 

5977 APPLICATION USAGE 

5978 Although chown () can be used on some systems by the file owner to change the owner and 

5979 group to any desired values, the only portable use of this function is to change the group of a file 

5980 to the effective GID of the calling process or to a member of its group set. 

5981 RATIONALE 

5982 System III and System V allow a user to give away files; that is, the owner of a file may change 

5983 its user ID to anything. This is a serious problem for implementations that are intended to meet 

5984 government security regulations. Version 7 and 4.3 BSD permit only the superuser to change the 

5985 user ID of a file. Some government agencies (usually not ones concerned directly with security) 

5986 find this limitation too confining. This volume of IEEE Std. 1003.1-200x uses may to permit 

5987 secure implementations while not disallowing System V. 

5988 System III and System V allow the owner of a file to change the group ID to anything. Version 7 

5989 permits only the superuser to change the group ID of a file. 4.3 BSD permits the owner to 

5990 change the group ID of a file to its effective group ID or to any of the groups in the list of 

5991 supplementary group IDs, but to no others. 

5992 The POSIX.1-1990 standard requires that the chozvn() function invoked by a non-appropriate I 

5993 privileged process clear the S_ISGID and the S_ISUID bits for regular files, and permits them to I 

5994 be cleared for other types of files. This is so that changes in accessibility do not accidentally I 

5995 cause files to become security holes. Unfortunately, requiring these bits to be cleared on non- I 

5996 executable data files also clears the mandatory file locking bit (shared with S_ISGID), which is I 

5997 an extension on many implementations (it first appeared in System V). These bits should only be I 

5998 required to be cleared on regular files that have one or more of their execute bits set. I 

5999 FUTURE DIRECTIONS 

6000 None. 

6001 SEE ALSO 

6002 chmod (), pathconfi ), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

6003 <sys/types.h>, <unistd.h> 
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6004 CHANGE HISTORY 

6005 First released in Issue 1. 

6006 Derived from Issue 1 of the SVID. 

6007 Issue 4 

6008 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

6009 XSI-conformant systems. 

6010 The value for owner of (uid_t)-l is added to the DESCRIPTION to allow the use of -1 by the 

6011 owner of a file to change the group ID only. 

6012 The APPLICATION USAGE section is added. 

6013 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

6014 • The type of argument path is changed from char* to const char*. 

6015 The following changes are incorporated for alignment with the FIPS requirements: 

6016 • In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 

6017 name component is larger that |NAME_MAX} is now defined as mandatory and marked as 

6018 an extension. 

6019 • In the ERRORS section, the condition whereby [EPERM] is returned when an attempt is 

6020 made to change the user ID of a file and the caller does not have appropriate privileges is 

6021 now defined as mandatory and marked as an extension. 

6022 Issue 4, Version 2 

6023 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 

6024 • It states that [ELOOP] is returned if too many symbolic links are encountered during path 

6025 name resolution. 

6026 • The [EIO] and [EINTR] optional conditions are added. 

6027 • A second [ENAMETOOLONG] condition is defined that may report excessive length of an 

6028 intermediate result of path name resolution of a symbolic link. 

6029 Issue 6 

6030 The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

6031 • The wording describing the optional dependency on _POSIX_CHOWN_RESTRICTED is 

6032 restored. 

6033 • The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 

6034 This is since behavior may vary from one file system to another. 

6035 • The [EPERM] error is restored as an error dependent on _POSIX_CHOWN_RESTRICTED. 

6036 This is since its operand is a path name and applications should be aware that the error may 

6037 not occur for that path name if the file system does not support 

6038 _POSIX_CHO WN_RESTRIC TED. 

6039 The following new requirements on POSIX implementations derive from alignment with the 

6040 Single UNIX Specification: 

6041 • The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 

6042 required for conforming implementations of previous POSIX specifications, it was not 

6043 required for UNIX applications. 

6044 • The value for owner of (uid_t)-l allows the use of -1 by the owner of a file to change the 

6045 group ID only. 


190 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


chown() 


6046 

6047 

6048 

6049 

6050 

6051 

6052 


• The [ELOOP] mandatory error condition is added. 

• The [EIO] and [EINTR] optional error conditions are added. 

• A second [ENAMETOOLONG] is added as an optional error condition. 

The following changes were made to align with the IEEE P1003.1a draft standard: I 

• Clarification is added that the S_ISUID and S_ISGID bits do not need to be cleared when the I 
process has appropriate privileges. 

• The [ELOOP] optional error condition is added. I 
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6053 NAME 

6054 clearerr — clear indicators on a stream 

6055 SYNOPSIS 

6056 tinclude <stdio.h> 

6057 void clearerr (FILE * stream); 

6058 DESCRIPTION 

6059 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

6060 conflict between the requirements described here and the ISO C standard is unintentional. This I 

6061 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

6062 The clearerr( ) function shall clear the end-of-file and error indicators for the stream to which 

6063 stream points. 

6064 RETURN VALUE 

6065 The clearerr( ) function shall return no value. 

6066 ERRORS 

6067 No errors are defined. 

6068 EXAMPLES 

6069 None. 

6070 APPLICATION USAGE 

6071 None. 

6072 RATIONALE 

6073 None. 

6074 FUTURE DIRECTIONS 

6075 None. 

6076 SEE ALSO 

6077 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdio.h> 

6078 CHANGE HISTORY 

6079 First released in Issue 1. 

6080 Derived from Issue 1 of the SVID. 
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6081 NAME 

6082 clock — report CPU time used 

6083 SYNOPSIS 

6084 #include <time.h> 

6085 clock_t clock (void) ; 

6086 DESCRIPTION 

6087 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

6088 conflict between the requirements described here and the ISO C standard is unintentional. This I 

6089 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

6090 The clock () function shall return the implementation's best approximation to the processor time 

6091 used by the process since the beginning of an implementation-dependent time related only to 

6092 the process invocation. 

6093 RETURN VALUE 

6094 To determine the time in seconds, the value returned by clock () should be divided by the value 

6095 xsi of the macro CLOCKS_PER_SEC. CLOCKS_PER_SEC is defined to be one million in <time.h>. 

6096 If the processor time used is not available or its value cannot be represented, the function shall 

6097 return the value (clock_t)-l . 

6098 ERRORS 

6099 No errors are defined. 

6100 EXAMPLES 

6101 None. 

6102 APPLICATION USAGE 

6103 In order to measure the time spent in a program, clock () should be called at the start of the 

6104 program and its return value subtracted from the value returned by subsequent calls. The value 

6105 returned by clock () is defined for compatibility across systems that have clocks with different 

6106 resolutions. The resolution on any particular system need not be to microsecond accuracy. 

6107 The value returned by clock( ) may wrap around on some systems. For example, on a machine 

6108 with 32-bit values for clock_t, it wraps after 2 147 seconds or 36 minutes. 

6109 RATIONALE 

6110 None. 

6111 FUTURE DIRECTIONS 

6112 None. 

6113 SEE ALSO 

6114 asctime( ), ctime( ), difftime( ), gmtime( ), localtime (), mktime (), strftime (), strptimei ), time (), utime (), 

6115 the System Interface Definitions volume of IEEE Std. 1003.1-200x, <time.h> 

6116 CHANGE HISTORY 

6117 First released in Issue 1. 

6118 Derived from Issue 1 of the SVID. 

6119 Issue 4 

6120 Reference to the resolution of CLOCKS_PER_SEC is marked as an extension. 

6121 The ERRORS section is added. 

6122 Advice on how to calculate the time spent in a program is added to the APPLICATION USAGE 

6123 section. 
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6124 The following changes are incorporated for alignment with the ISO C standard: 

6125 • The <time.h> header is added to the SYNOPSIS section. 

6126 • The DESCRIPTION and RETURN VALUE sections, though functionally equivalent to Issue 

6127 3, are rewritten for clarity and consistency with the ISO C standard. This issue also defines 

6128 under what circumstances (clock_t)-l can be returned by the function. 

6129 • The function is no longer marked as an extension. 
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6130 NAME 

6131 clock_getcpuclockid — access a process CPU-time clock (REALTIME) 

6132 SYNOPSIS 

6133 CPT #include <time.h> 

6134 clock_getcpuclockid (pid_t pid, clockid_t *clock_id) ; 

6135 

6136 DESCRIPTION 

6137 The clock_getcpuclockid () function shall return the clock ID of the CPU-time clock of the process 

6138 specified by pid . If the process described by pid exists and the calling process has permission, 

6139 the clock ID of this clock shall be returned in clock_id. 

6140 If pid is zero, the clock_getcpiiclockid () function shall return the clock ID of the CPU-time clock of 

6141 the process making the call, in dock_id. 

6142 The conditions under which one process has permission to obtain the CPU-time clock ID of 

6143 other processes are implementation-dependent. 

6144 RETURN VALUE 

6145 Upon successful completion, dock_getcpudockid() shall return zero; otherwise, an error number 

6146 shall be returned to indicate the error. 

6147 ERRORS 

6148 The dock_getcpudockid () function shall fail if: 

6149 [EPERM] The requesting process does not have permission to access the CPU-time 

6150 clock for the process. 

6151 The dock_getcpudockid () function may fail if: 

6152 [ESRCH] No process can be found corresponding to that specified by pid. 

6153 EXAMPLES 

6154 None. 

6155 APPLICATION USAGE 

6156 The dock_getcpudockid() function is part of the _POSIX_CPUTIME option and need not be 

6157 provided on all implementations. 

6158 RATIONALE 

6159 None. 

6160 FUTURE DIRECTIONS 

6161 None. 

6162 SEE ALSO 

6163 dock_getres(), tinier_create(), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

6164 <time.h> 

6165 CHANGE HISTORY 

6166 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 

6167 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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6168 NAME 

6169 clock_getres, clock_gettime, clock_settime — clock and timer functions (REALTIME) 

6170 SYNOPSIS 

6171 tmr #include <time.h> 

6172 

6173 

6174 

6175 

6176 DESCRIPTION 

6177 The resolution of any clock can be obtained by calling clock_getres(). Clock resolutions are 

6178 implementation-dependent and cannot be set by a process. If the argument res is not NULL, the 

6179 resolution of the specified clock shall be stored in the location pointed to by res . If res is NULL, 

6180 the clock resolution is not returned. If the time argument of clock_settime( ) is not a multiple of res, 

6181 then the value is truncated to a multiple of res. 

6182 The clock_gettime( ) function shall return the current value tp for the specified clock, clock_id. 

6183 The clock_settime() function shall set the specified clock, clock_id, to the value specified by tp. 

6184 Time values that are between two consecutive non-negative integer multiples of the resolution 

6185 of the specified clock are truncated down to the smaller multiple of the resolution. 

6186 A clock may be system-wide (that is, visible to all processes) or per-process (measuring time that 

6187 is meaningful only within a process). All implementations shall support a clock_id of 

6188 CLOCK_REALTIME defined in <time.h>. This clock represents the realtime clock for the 

6189 system. For this clock, the values returned by clock_gettime() and specified by clock_settime() 

6190 represent the amount of time (in seconds and nanoseconds) since the Epoch. An implementation 

6191 may also support additional clocks. The interpretation of time values for these clocks is 

6192 unspecified. 

6193 If the value of the CLOCK_REALTIME clock is set via clock_settime( ), the new value of the clock I 

6194 shall be used to determine the time of expiration for absolute time services based upon the I 

6195 CLOCK_REALTIME clock. This applies to the time at which armed absolute timers expire. If the I 

6196 absolute time requested at the invocation of such a time service is before the new value of the I 

6197 clock, the time service shall expire immediately as if the clock had reached the requested time I 

6198 normally. I 

6199 Setting the value of the CLOCK_REALTIME clock via clock_settime() shall have no effect on I 

6200 threads that are blocked waiting for a relative time service based upon this clock, including the I 

6201 nanosleep () function; nor on the expiration of relative timers based upon this clock. I 

6202 Consequently, these time services shall expire when the requested relative interval elapses, I 

6203 independently of the new or old value of the clock. I 

6204 mon If the Monotonic Clock option is supported, all implementations shall support a clock_id of I 

6205 CLOCK_MONOTONIC defined in <time.h>. This clock represents the monotonic clock for the I 

6206 system. For this clock, the value returned by clock_gettime( ) represents the amount of time (in I 

6207 seconds and nanoseconds) since an unspecified point in the past (for example, system start-up I 

6208 time, or the Epoch). This point does not change after system start-up time. The value of the I 

6209 CLOCK_MONOTONIC clock cannot be set via clock_settime(). This function shall fail if it is I 

6210 invoked with a clock_id argument of CLOCK_MONOTONIC. I 

6211 The effect of setting a clock via clock_settime( ) on armed per-process timers associated with a I 

6212 clock other than CLOCK_REALTIME is implementation-dependent. I 

6213 cs If the value of the CLOCK_REALTIME clock is set via clock_settime( ), the new value of the clock I 

6214 shall be used to determine the time at which the system shall awaken a thread blocked on an I 


int clock_getres(clockid_t clock_id, struct timespec *res) ; 

int clock_settime(clockid_t clock_id, const struct timespec *tp); 

int clock_gettime(clockid_t clock_id, struct timespec *tp) ; 
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6215 absolute clock_nanosleep() call based upon the CLOCK_REALTIME clock. If the absolute time 

6216 requested at the invocation of such a time service is before the new value of the clock, the call 

6217 shall return immediately as if the clock had reached the requested time normally. 

6218 Setting the value of the CLOCK_REALTIME clock via clock_settime( ) shall have no effect on any 

6219 thread that is blocked on a relative clock_nanosleep( ) call. Consequently, the call shall return 

6220 when the requested relative interval elapses, independently of the new or old value of the clock. 

6221 The appropriate privilege to set a particular clock is implementation-dependent. 

6222 cpt If _POSIX_CPUTIME is defined, implementations shall support clock ID values obtained by 

6223 invoking clock_getcpuclockid(), which represent the CPU-time clock of a given process. 

6224 Implementations shall also support the special clockid_t value 

6225 CLOCK_PROCESS_CPUTIME_ID, which represents the CPU-time clock of the calling process 

6226 when invoking one of the dock( ) or timer*( ) functions. For these clock IDs, the values returned 

6227 by clock_gettime( ) and specified by clock_settime( ) represent the amount of execution time of the 

6228 process associated with the clock. Changing the value of a CPU-time clock via dock_settime() 

6229 shall have no effect on the behavior of the sporadic server scheduling policy (see Scheduling 

6230 Policies on page 63). 

6231 tct If _POSIX_THREAD_CPUTIME is defined, implementations shall support clock ID values 

6232 obtained by invoking pthread_getcpnclockid{), which represent the CPU-time clock of a given 

6233 thread. Implementations shall also support the special clockid_t value 

6234 CLOCK_THREAD_CPUTIME_ID, which represents the CPU-time clock of the calling thread 

6235 when invoking one of the dock( ) or timer* () functions. For these clock IDs, the values returned 

6236 by clock_gettime( ) and specified by clock_settime( ) represent the amount of execution time of the 

6237 thread associated with the clock. Changing the value of a CPU-time clock via clock_settime( ) 

6238 shall have no effect on the behavior of the sporadic server scheduling policy (see Scheduling 

6239 Policies on page 63). 

6240 RETURN VALUE 

6241 A return value of 0 shall indicate that the call succeeded. A return value of -1 shall indicate that 

6242 an error occurred, and errno shall be set to indicate the error. 

6243 ERRORS 

6244 The clock_getres (), clock_gettime( ), and dock_settime( ) functions shall fail if: 

6245 [EINVAL] The clock_id argument does not specify a known clock. 

6246 The clock_settime( ) function shall fail if: 

6247 [EINVAL] The tp argument to clock_settime( ) is outside the range for the given clock ID. 

6248 [EINVAL] The tp argument specified a nanosecond value less than zero or greater than 

6249 or equal to 1000 million. I 

6250 mon [EINVAL] The value of the dock_id argument is CLOCK_MONOTONIC. I 

6251 The clock_settime( ) function may fail if: 

6252 [EPERM] The requesting process does not have the appropriate privilege to set the 

6253 specified clock. 
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6254 EXAMPLES 

6255 None. 

6256 APPLICATION USAGE 

6257 These functions are part of the _POSIX_TIMERS option and need not be available on all 

6258 implementations. I 

6259 Note that the absolute value of the monotonic clock is meaningless (because its origin is I 

6260 arbitrary), and thus there is no need to set it. Furthermore, realtime applications can rely on the I 

6261 fact that the value of this clock is never set and, therefore, that time intervals measured with this I 

6262 clock will not be affected by calls to clock_settime( ). I 

6263 RATIONALE 

6264 None. 

6265 FUTURE DIRECTIONS 

6266 None. 

6267 SEE ALSO 

6268 clock_getcpuclockid( ), clock_nanosleep( ), ctime (), mq_timedreceive (), mqjimedsend (), nanosleep (), I 

6269 pthread_mutexJimedlock (), sem_timedivait{ ), time( ), timer_create{ ), timer_getoverrun (), the System I 

6270 Interface Definitions volume of IEEE Std. 1003.1-200x, <time.h> I 

6271 CHANGE HISTORY 

6272 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 

6273 Issue 6 

6274 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

6275 implementation does not support the _POSIX_TIMERS option. 

6276 The APPLICATION USAGE section is added. I 

6277 The following changes were made to align with the IEEE P1003.1a draft standard: I 

6278 • Clarification is added of the effect of resetting the clock resolution. I 

6279 CPU-time clocks and the clock_getcpuclockid() function are added for alignment with I 

6280 IEEE Std. 1003.1d-1999. I 

6281 The following changes are added for alignment with IEEE Std. 1003.1j-2000: I 

6282 • The DESCRIPTION is updated as follows: I 

6283 — The value returned by clock_gettime() for CLOCK_MONOTONIC is specified. I 

6284 — clock_settime( ) failing for CLOCK_MONOTONIC is specified. I 

6285 — The effects of clock_settime() on the clock_nanosleep{) function with respect to I 

6286 CLOCK_REALTIME is specified. I 

6287 • An [EINVAL] error is added to the ERRORS section, indicating that clock_settime( ) fails for I 

6288 CLOCK_MONOT ONIC. I 

6289 • The APPLICATION USAGE section notes that the CLOCK_MONOTONIC clock need not I 

6290 and shall not be set by clock_settime( ) since the absolute value of the CLOCK_MONOTONIC I 

6291 clock is meaningless. I 

6292 • The clock_nanosleep(), mqjimedreceivei ), mqjtimedsend (), pthread_mutexJimedlock{), I 

6293 semjimedwa.it (), timer_create(), and timer_settime () functions are added to the SEE ALSO I 

6294 section. I 
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6295 NAME 

6296 clock_nanosleep — high resolution sleep with specifiable clock 

6297 SYNOPSIS 

6298 CS #include <time.h> 

6299 

6300 

6301 

6302 DESCRIPTION 

6303 If the flag TIMER_ABSTIME is not set in th eflags argument, the clock_nanosleep() function shall 

6304 cause the current thread to be suspended from execution until either the time interval specified 

6305 by the rqtp argument has elapsed, or a signal is delivered to the calling thread and its action is to 

6306 invoke a signal-catching function, or the process is terminated. The clock used to measure the 

6307 time shall be the clock specified by clock_id. 

6308 If the flag TIMER_ABSTIME is set in the flags argument, the clock_nanosleep() function shall 

6309 cause the current thread to be suspended from execution until either the time value of the clock 

6310 specified by clock_id reaches the absolute time specified by the rqtp argument, or a signal is 

6311 delivered to the calling thread and its action is to invoke a signal-catching function, or the 

6312 process is terminated. If, at the time of the call, the time value specified by rqtp is less than or 

6313 equal to the time value of the specified clock, then clock_nanosleep{) shall return immediately 

6314 and the calling process shall not be suspended. 

6315 The suspension time caused by this function may be longer than requested because the 

6316 argument value is rounded up to an integer multiple of the sleep resolution, or because of the 

6317 scheduling of other activity by the system. But, except for the case of being interrupted by a 

6318 signal, the suspension time for the relative clock_nanosleep() function (that is, with the 

6319 TIMER_ABSTIME flag not set) shall not be less than the time interval specified by rqtp, as 

6320 measured by the corresponding clock. The suspension for the absolute dock_nanosleep{) function 

6321 (that is, with the TIMER_ABSTIME flag set) shall be in effect at least until the value of the 

6322 corresponding clock reaches the absolute time specified by rqtp, except for the case of being 

6323 interrupted by a signal. 

6324 The use of the dock_nanosleep() function shall have no effect on the action or blockage of any 

6325 signal. 

6326 The dock_nanosleep() function shall fail if the dock_id argument refers to the CPU-time clock of 

6327 the calling thread. It is unspecified if dock_id values of other CPU-time clocks are allowed. 

6328 RETURN VALUE 

6329 If the dock_nanosleep( ) function returns because the requested time has elapsed, its return value 

6330 shall be zero. 

6331 If the dock_nanosleep( ) function returns because it has been interrupted by a signal, it shall return 

6332 the corresponding error value. For the relative dock_nanosleep() function, if the rmtp argument is 

6333 non-NULL, the timespec structure referenced by it shall be updated to contain the amount of 

6334 time remaining in the interval (the requested time minus the time actually slept). If the rmtp 

6335 argument is NULL, the remaining time is not returned. The absolute dock_nanosleep{) function 

6336 has no effect on the structure referenced by rmtp. 

6337 If dock_nanosleep () fails, it shall return the corresponding error value. 


int clock_nanosleep(clockid_t clock_id, int flags, 

const struct timespec * rqtp, struct timespec * rmtp); 
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6338 ERRORS 

6339 The clock_nanosleep( ) function shall fail if: 

6340 [EINTR] The clock_nanosleep( ) function was interrupted by a signal. 

6341 [EINVAL] The rqtp argument specified a nanosecond value less than zero or greater than 

6342 or equal to 1000 million; or the TIMER_ABSTIME flag was specified in flags 

6343 and the rqtp argument is outside the range for the clock specified by clock_id ; 

6344 or the clock_id argument does not specify a known clock, or specifies the 

6345 CPU-time clock of the calling thread. 

6346 [ENOTSUP] The clock_id argument specifies a clock for which clock_nanosleep() is not 

6347 supported, such as a CPU-time clock. 

6348 EXAMPLES 

6349 None. 

6350 APPLICATION USAGE 

6351 Calling clock_nanosleep( ) with the value TIMER_ABSTIME not set in the flags argument and with 

6352 a clock_id of CLOCK_REALTIME is equivalent to calling nanosleep ( ) with the same rqtp and rmtp 

6353 arguments. 

6354 RATIONALE 

6355 The nanosleep () function specifies that the system-wide clock CLOCK_REALTIME is used to 

6356 measure the elapsed time for this time service. However, with the introduction of the monotonic 

6357 clock CLOCK_MONOTONIC a new relative sleep function is needed to allow an application to 

6358 take advantage of the special characteristics of this clock. 

6359 There are many applications in which a process needs to be suspended and then activated 

6360 multiple times in a periodic way; for example, to poll the status of a non-interrupting device or 

6361 to refresh a display device. For these cases, it is known that precise periodic activation cannot be 

6362 achieved with a relative sleep () or nanosleep () function call. Suppose, for example, a periodic 

6363 process that is activated at time TO, executes for a while, and then wants to suspend itself until 

6364 time T0+T, the period being T. If this process wants to use the nanosleep () function, it must first 

6365 call clock_gettime( ) to get the current time, then calculate the difference between the current time 

6366 and T0+T and, finally, call nanosleep () using the computed interval. However, the process could 

6367 be preempted by a different process between the two function calls, and in this case the interval 

6368 computed would be wrong; the process would wake up later than desired. This problem would 

6369 not occur with the absolute clock_nanosleep( ) function, since only one function call would be 

6370 necessary to suspend the process until the desired time. In other cases, however, a relative sleep 

6371 is needed, and that is why both functionalities are required. 

6372 Although it is possible to implement periodic processes using the timers interface, this 

6373 implementation would require the use of signals, and the reservation of some signal numbers. In 

6374 this regard, the reasons for including an absolute version of the clock_nanosleep() function in 

6375 IEEE Std. 1003.1-200x are the same as for the inclusion of the relative nanosleep( ). 

6376 It is also possible to implement precise periodic processes using pthread_cond_timedwait( ), in 

6377 which an absolute timeout is specified that takes effect if the condition variable involved is 

6378 never signaled. However, the use of this interface is unnatural, and involves performing other 

6379 operations on mutexes and condition variables that imply an unnecessary overhead. 

6380 Furthermore, pthread_cond_timedwait( ) is not available in implementations that do not support 

6381 threads. 

6382 Although the interface of the relative and absolute versions of the new high resolution sleep 

6383 service is the same clock_nanosleep() function, the rmtp argument is only used in the relative 

6384 sleep. This argument is needed in the relative clock_nanosleep( ) function to reissue the function 
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6385 call if it is interrupted by a signal, but it is not needed in the absolute clock_nanosleep() function 

6386 call; if the call is interrupted by a signal, the absolute clock_nanosleep( ) function can be invoked 

6387 again with the same rqtp argument used in the interrupted call. 

6388 FUTURE DIRECTIONS 

6389 None. 

6390 SEE ALSO 

6391 clock_getres(), nanosleep(), pthread_cond_timedwait( ), sleep(), the System Interface Definitions 

6392 volume of IEEE Std. 1003.1-200x, <time.h> 

6393 CHANGE HISTORY 

6394 First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. 
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6395 NAME 

6396 close — close a file descriptor 

6397 SYNOPSIS 

6398 #include <unistd.h> 

6399 int close (int fildes) ; 

6400 DESCRIPTION 

6401 The close () function shall deallocate the file descriptor indicated by fildes. To deallocate means 

6402 to make the file descriptor available for return by subsequent calls to open () or other functions 

6403 that allocate file descriptors. All outstanding record locks owned by the process on the file 

6404 associated with the file descriptor shall be removed (that is, unlocked). 

6405 If close () is interrupted by a signal that is to be caught, it shall return -1 with errno set to [EINTR] 

6406 and the state of fildes is unspecified. If an I/O error occurred while reading from or writing to the 

6407 file system during close (), it may return -1 with errno set to [EIO]; if this error is returned, the 

6408 state of fildes is unspecified. 

6409 When all file descriptors associated with a pipe or FIFO special file are closed, any data 

6410 remaining in the pipe or FIFO shall be discarded. 

6411 When all file descriptors associated with an open file description have been closed the open file 

6412 description shall be freed. 

6413 If the link count of the file is 0, when all file descriptors associated with the file are closed, the 

6414 space occupied by the file shall be freed and the file shall no longer be accessible. 

6415 xsr If a STREAMS-based fildes is closed and the calling process was previously registered to receive I 

6416 a SIGPOLL signal for events associated with that STREAM, the calling process shall be 

6417 unregistered for events associated with the STREAM. The last close () for a STREAM causes the 

6418 STREAM associated with fildes to be dismantled. If 0_NONBLOCK is not set and there have 

6419 been no signals posted for the STREAM, and if there is data on the module's write queue, close () 

6420 waits for an unspecified time (for each module and driver) for any output to drain before 

6421 dismantling the STREAM. The time delay can be changed via an I_SETCLTIME ioctl () request. If 

6422 the 0_NONBLOCK flag is set, or if there are any pending signals, close () does not wait for 

6423 output to drain, and dismantles the STREAM immediately. 

6424 If the implementation supports STREAMS-based pipes, and fildes is associated with one end of a 

6425 pip e / the last close () causes a hangup to occur on the other end of the pipe. In addition, if the 

6426 other end of the pipe has been named by fattach (), then the last close () forces the named end to 

6427 be detached by fdetach (). If the named end has no open file descriptors associated with it and 

6428 gets detached, the STREAM associated with that end is also dismantled. 

6429 If fildes refers to the master side of a pseudo-terminal, and this is the last close, a SIGHUP signal 

6430 is sent to the process group, if any, for which the slave side of the pseudo-terminal is the 

6431 controlling terminal. It is unspecified whether closing the master side of the pseudo-terminal 

6432 flushes all queued input and output. 

6433 If fildes refers to the slave side of a STREAMS-based pseudo-terminal, a zero-length message 

6434 may be sent to the master. 

6435 aio When there is an outstanding cancelable asynchronous I/O operation against fildes when close( ) 

6436 is called, that I/O operation may be canceled. An I/O operation that is not canceled completes 

6437 as if the close () operation had not yet occurred. All operations that are not canceled shall 

6438 complete as if the close () blocked until the operations completed. The close () operation itself 

6439 need not block awaiting such I/O completion. Whether any I/O operation is canceled, and 

6440 which I/O operation may be canceled upon close( ), is implementation-dependent. 
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6441 mf i shm If a shared memory object or a memory mapped file remains referenced at the last close (that is, 

6442 a process has it mapped), then the entire contents of the memory object shall persist until the 

6443 memory object becomes unreferenced. If this is the last close of a shared memory object or a 

6444 memory mapped file and the close results in the memory object becoming unreferenced, and the 

6445 memory object has been unlinked, then the memory object shall be removed. 

6446 If fildes refers to a socket, close {) shall cause the socket to be destroyed. If the socket is in 

6447 connection-mode, and the SO_LINGER option is set for the socket with non-zero linger time, 

6448 and the socket has untransmitted data, then close () shall block for up to the current linger 

6449 interval until all data is transmitted. 

6450 RETURN VALUE 

6451 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 

6452 indicate the error. 

6453 ERRORS 

6454 The close ( ) function shall fail if: 

6455 [EBADF] Th e fildes argument is not a valid file descriptor. 

6456 [EINTR] The close () function was interrupted by a signal. 

6457 The close () function may fail if: 

6458 man [EIO] An I/O error occurred while reading from or writing to the file system. 

6459 EXAMPLES 

6460 Reassigning a File Descriptor 

6461 The following example closes the file descriptor associated with standard output for the current 

6462 process, re-assigns standard output to a new file descriptor, and closes the original file 

6463 descriptor to clean up. 

6464 #include <unistd.h> 

6465 

6466 int pfd; 

6467 

6468 close (1 ) ; 

6469 dup (pfd) ; 

6470 close (pfd) ; 

6471 

6472 Closing a File Descriptor 

6473 In the following example, close () is used to close a file descriptor after an unsuccessful attempt is 

6474 made to associate that file descriptor with a stream. 

6475 tinclude <stdio.h> 

6476 tinclude <unistd.h> 

6477 #include <stdlib.h> 

6478 #define LOCKFILE "/etc/ptmp" 

6479 

6480 int pfd; 

6481 FILE *fpfd; 

6482 

6483 if ( (fpfd = fdopen (pfd, "w")) == NULL) { 
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6484 close (pfd) ; 

6485 unlink (LOCKFILE) ; 

6486 exit (1); 

6487 } 

6488 

6489 APPLICATION USAGE 

6490 An application that had used the stdio routine fopen() to open a file should use the 

6491 corresponding /close () routine rather than close (). Once a file is closed, the file descriptor no I 

6492 longer exists, since the integer corresponding to it no longer refers to a file. 

6493 RATIONALE 

6494 The use of interruptible device close routines should be discouraged to avoid problems with the 

6495 implicit closes of file descriptors by exec and exit(). this volume of IEEEStd. 1003.1-200x only 

6496 intends to permit such behavior by specifying the [EINTR] error condition. 

6497 FUTURE DIRECTIONS 

6498 None. 

6499 SEE ALSO 

6500 fattach (), /close (), /detach (), /open (), ioctl(), open(), the System Interface Definitions volume of 

6501 IEEE Std. 1003.1-200x, <unistd.h>. Section 2.6 on page 55 

6502 CHANGE HISTORY 

6503 First released in Issue 1. 

6504 Derived from Issue 1 of the SVID. 

6505 Issue 4 

6506 The <unistd.h> header is added to the SYNOPSIS section. 

6507 Issue 4, Version 2 

6508 The following changes are incorporated for X/OPEN UNIX conformance: 

6509 • The DESCRIPTION is updated to describe the actions of closing a file descriptor referring to 

6510 a STREAMS-based file or either side of a pseudo-terminal. 

6511 • The ERRORS section describes a condition under which the [EIO] error may be returned. 

6512 Issue 5 

6513 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 

6514 Issue 6 

6515 The DESCRIPTION related to a STREAMS-based file or pseudo-terminal is marked as part of the I 

6516 XSI STREAMS Option Group. I 

6517 The following new requirements on POSIX implementations derive from alignment with the I 

6518 Single UNIX Specification: 

6519 • The [EIO] error condition is added as an optional error. 

6520 • The DESCRIPTION is updated to describe the state of th efildes file descriptor as unspecified 

6521 if an I/O error occurs and an [EIO] error condition is returned. 

6522 Text referring to sockets is added to the DESCRIPTION. I 

6523 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that I 

6524 shared memory objects and memory mapped files (and not typed memory objects) are the types I 

6525 of memory objects to which the paragraph on last closes applies. I 
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6526 NAME 

6527 closedir — close a directory stream 

6528 SYNOPSIS 

6529 #include <dirent.h> 

6530 int closedir (DIR *dirp ); 

6531 DESCRIPTION 

6532 The closedir () function shall close the directory stream referred to by the argument dirp. Upon 

6533 return, the value of dirp may no longer point to an accessible object of the type DIR. If a file 

6534 descriptor is used to implement type DIR, that file descriptor shall be closed. 

6535 RETURN VALUE 

6536 Upon successful completion, closedir() shall return 0; otherwise, -1 shall be returned and errno 

6537 set to indicate the error. 

6538 ERRORS 

6539 The closedir () function may fail if: 

6540 [EBADF] The dirp argument does not refer to an open directory stream. 

6541 man [EINTR] The closedir () function was interrupted by a signal. 

6542 EXAMPLES 

6543 Closing a Directory Stream 

6544 The following program fragment demonstrates how the closedir () function is used. 

6545 

6546 DIR *dir; 

6547 struct dirent *dp; 

6548 

6549 if ((dir = opendir (".")) == NULL) { 

6550 

6551 } 

6552 while ((dp = readdir (dir)) != NULL) { 

6553 

6554 } 

6555 closedir (dir) ; 

6556 

6557 APPLICATION USAGE 

6558 None. 

6559 RATIONALE 

6560 None. 

6561 FUTURE DIRECTIONS 

6562 None. 

6563 SEE ALSO 

6564 opendir( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <dirent.h> 
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6565 CHANGE HISTORY 

6566 First released in Issue 2. 

6567 Issue 4 

6568 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

6569 XSI-conformant systems. 

6570 The [EINTR] error is marked as an extension. 

6571 Issue 6 

6572 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

6573 The following new requirements on POSIX implementations derive from alignment with the 

6574 Single UNIX Specification: 

6575 • The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 

6576 required for conforming implementations of previous POSIX specifications, it was not 

6577 required for UNIX applications. 

6578 • The [EINTR] error condition is added as an optional error condition. 
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6579 NAME 

6580 closelog, openlog, setlogmask, syslog — control system log 

6581 SYNOPSIS 

6582 xsi tinclude <syslog.h> 


6583 

void closelog(void) ; 

6584 

void openlog(const char *ident, int logopt, int facility); 

6585 

int setlogmask(int maskpri); 

6586 

void syslog(int priority, const char *message, ... /* arguments */); 


6587 


6588 DESCRIPTION 

6589 The syslog () function shall send a message to an implementation-dependent logging facility, 

6590 which may log it in an implementation-dependent system log, write it to the system console, 

6591 forward it to a list of users, or forward it to the logging facility on another host over the network. 

6592 The logged message shall include a message header and a message body. The message header 

6593 contains at least a timestamp and a tag string. 

6594 The message body is generated from the message and following arguments in the same manner 

6595 as if these were arguments to printf(), except that occurrences of %m in the format string 

6596 pointed to by the message argument are replaced by the error message string associated with the 

6597 current value of errno. A trailing <newline> character is added if needed. 

6598 Values of the priority argument are formed by OR'ing together a severity level value and an 

6599 optional facility value. If no facility value is specified, the current default facility value is used. 

6600 Possible values of severity level include: 

6601 LOG_EMERG A panic condition. 

6602 LOG_ALERT A condition that should be corrected immediately, such as a corrupted system 

6603 database. 


6604 

6605 

6606 

6607 

6608 

6609 

6610 

6611 

6612 

6613 

6614 

6615 

6616 

6617 

6618 
6619 


LOG_CRIT Critical conditions, such as hard device errors. 

LOG_ERR Errors. 

LOG_WARNING 

Warning messages. 

LOG_NOTICE Conditions that are not error conditions, but that may require special 
handling. 

LOG_INFO Informational messages. 

LOG_DEBUG Messages that contain information normally of use only when debugging a 

program. 

The facility indicates the application or system component generating the message. Possible 
facility values include: 


LOG_USER 

LOG_LOCALO 

LOG_LOCALl 

LOG_LOCAL2 


Messages generated by random processes. This is the default facility identifier 
if none is specified. 

Reserved for local use. 

Reserved for local use. 

Reserved for local use. 
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6620 

LOG_LOCAL3 

Reserved for local use. 

6621 

LOG_LOCAL4 

Reserved for local use. 

6622 

LOG_LOCAL5 

Reserved for local use. 

6623 

LOG_LOCAL6 

Reserved for local use. 

6624 

LOG_LOCAL7 

Reserved for local use. 

6625 

6626 

6627 

6628 

The openlog () function shall set process attributes that affect subsequent calls to syslogO■ The 
ident argument is a string that is prepended to every message. The logopt argument indicates 
logging options. Values for logopt are constructed by a bitwise-inclusive OR of zero or more of 
the following: 

6629 

6630 

LOG_PID 

Log the process ID with each message. This is useful for identifying specific 
processes. 

6631 

6632 

6633 

LOG_CONS 

Write messages to the system console if they cannot be sent to the logging 
facility. The syslogO function ensures that the process does not acquire the 
console as a controlling terminal in the process of writing the message. 

6634 

6635 

6636 

LOG_NDELAY 

Open the connection to the logging facility immediately. Normally the open is 
delayed until the first message is logged. This is useful for programs that need 
to manage the order in which file descriptors are allocated. 

6637 

LOG_ODELAY 

Delay open until syslog( ) is called. 

6638 

6639 

6640 

6641 

6642 

LOG_NOWAIT 

Do not wait for child processes that may have been created during the course 
of logging the message. This option should be used by processes that enable 
notification of child termination using SIGCHLD, since syslogO may 
otherwise block waiting for a child whose exit status has already been 
collected. 


6643 The facility argument encodes a default facility to be assigned to all messages that do not have 

6644 an explicit facility already encoded. The initial default facility is LOG_USER. 

6645 The openlogO and syslogO functions may allocate a file descriptor. It is not necessary to call 

6646 openlog ( ) prior to calling syslog (). 

6647 The closelogO function shall close any open file descriptors allocated by previous calls to 

6648 openlog ( ) or syslog (). 

6649 The setlogmaskO function shall set the log priority mask for the current process to maskpri and 

6650 return the previous mask. If the maskpri argument is 0, the current log mask is not modified. 

6651 Calls by the current process to syslogO with a priority not set in maskpri shall be rejected. The 

6652 default log mask allows all priorities to be logged. A call to openlog is not required prior to 

6653 calling setlogmask (). 

6654 Symbolic constants for use as values of the logopt, facility, priority, and maskpri arguments are 

6655 defined in the <syslog.h> header. 

6656 RETURN VALUE 

6657 The setlogmask () function shall return the previous log priority mask. The closelogO, openlog (), 

6658 and syslog( ) functions shall return no value. 

6659 ERRORS 

6660 No errors are defined. 
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6661 EXAMPLES 

6662 Using openlog( ) 

6663 The following example causes subsequent calls to syslog () to log the process ID with each 

6664 message, and to write messages to the system console if they cannot be sent to the logging 

6665 facility. 

6666 #include <syslog.h> 

6667 char *ident = "Process demo"; 

6668 int logopt = LOG_PID | LOG_CONS; 

6669 int facility = LOG_USER; 

6670 

6671 openlog (ident, logopt, facility) ; 

6672 Using setlogmask() 

6673 The following example causes subsequent calls to syslog( ) to accept error messages or messages 

6674 generated by random processes, and to reject all other messages. 

6675 #include <syslog.h> 

6676 int result; 

6677 int mask = LOG_MASK (LOG_ERR | LOG_USER) ; 

6678 

6679 result = setlogmask (mask) ; 

6680 Using syslog 

6681 The following example sends the message "This is a message" to the default logging 

6682 facility, marking the message as an error message generated by random processes. 

6683 #include <syslog.h> 

6684 char ‘message = "This is a message"; 

6685 int priority = LOG_ERR | LOG_USER; 

6686 

6687 syslog (priority, message) ; 

6688 APPLICATION USAGE 

6689 None. 

6690 RATIONALE 

6691 None. 

6692 FUTURE DIRECTIONS 

6693 None. 

6694 SEE ALSO 

6695 printf( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <syslog.h> 

6696 CHANGE HISTORY 

6697 First released in Issue 4, Version 2. 
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6698 Issue 5 

6699 Moved from X/OPEN UNIX extension to BASE. 
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6700 NAME 

6701 confstr — get configurable variables 

6702 SYNOPSIS 

6703 tinclude <unistd.h> 

6704 size_t confstr (int name, char *buf, size_t len) ; 

6705 DESCRIPTION 

6706 The confstr () function provides a method for applications to get configuration-defined string 

6707 values. Its use and purpose are similar to sysconf( ), but it is used where string values rather than 

6708 numeric values are returned. 

6709 The name argument represents the system variable to be queried. The implementation shall 

6710 support the following name values, defined in <unistd.h>. It may support others: 

6711 _CS_PATH 

6712 MAN 

6713 

6714 

6715 

6716 

6717 

6718 

6719 

6720 

6721 

6722 

6723 

6724 

6725 

6726 

6727 

6728 

6729 If ten is not 0, and if name has a configuration-defined value, confstr () shall copy that value into 

6730 the len- byte buffer pointed to by bitf. If the string to be returned is longer than len bytes, 

6731 including the terminating null, then confstr () shall truncate the string to len- 1 bytes and null- 

6732 terminate the result. The application can detect that the string was truncated by comparing the 

6733 value returned by confstr () with len. 

6734 If len is 0 and buf is a null pointer, then confstr () shall still return the integer value as defined 

6735 below, but shall not return a string. If len is 0 but buf is not a null pointer, the result is 

6736 unspecified. 

6737 If the implementation supports the POSIX Shell option, the string stored in buf after a call to: 

6738 confstr (_CS_PATH, buf, sizeof (buf) ) 

6739 can be used as a value of the PATH environment variable that accesses all of the standard 

6740 utilities of IEEE Std. 1003.1-200x, if the return value is less than or equal to sizeof (buf). 

6741 RETURN VALUE 

6742 If name has a configuration-defined value, confstr () shall return the size of buffer that would be 

6743 needed to hold the entire configuration-defined value including the terminating null. If this 

6744 return value is greater than len, the string returned in buf is truncated. 


CS_XBS5_ILP32_OFF32_CFLAGS 

CS_XBS5_ILP32_OFF32_LDFLAGS 

GS_XBS5_ILP32_OFF32_LIBS 

GS_XBS5_ILP32_OFF32_LINTFLAGS 

GS_XBS5_ILP32_OFFBIG_CFLAGS 

GS_XBS5_ILP32_OFFBIG_LDFLAGS 

GS_XBS5_ILP32_OFFBIG_LIBS 

GS_XBS5_ILP32_OFFBIG_LINTFLAGS 

GS_XBS5_LP64_OFF64_CFLAGS 

GS_XBS5_LP64_OFF64_LDFLAGS 

GS_XBS5_LP64_OFF64_LIBS 

GS_XBS5_LP64_OFF64_LINTFLAGS 

GS_XBS5_LPBIG_OFFBIG_CFLAGS 

GS_XBS5_LPBIG_OFFBIG_LDFLAGS 

GS_XBS5_LPBIG_OFFBIG_LIBS 

GS_XBS5_LPBIG_OFFBIG_LINTFLAGS 


System Interfaces, Issue 6 


211 





confstr() 


System Interfaces 


6745 If name is invalid, confstr( ) shall return 0 and set errno to indicate the error. 

6746 If name does not have a configuration-defined value, confstr() shall return 0 and leave errno 

6747 unchanged. 

6748 ERRORS 

6749 The confstr( ) function shall fail if: 

6750 [EINVAL] The value of the name argument is invalid. 

6751 EXAMPLES 

6752 None. 

6753 APPLICATION USAGE 

6754 An application can distinguish between an invalid name parameter value and one that 

6755 corresponds to a configurable variable that has no configuration-defined value by checking if 

6756 errno is modified. This mirrors the behavior of sysconf (). 

6757 The original need for this function was to provide a way of finding the configuration-defined 

6758 default value for the environment variable PATH. Since PATH can be modified by the user to 

6759 include directories that could contain utilities replacing the standard utilities in the Commands 

6760 and Utilities volume of IEEE Std. 1003.1-200x, applications need a way to determine the system- 

6761 supplied PATH environment variable value that contains the correct search path for the standard 

6762 utilities. 

6763 An application could use: 

6764 confstr (name, (char *)NULL, (size_t)0) 

6765 to find out how big a buffer is needed for the string value; use malloc{ ) to allocate a buffer to 

6766 hold the string; and call confstr() again to get the string. Alternately, it could allocate a fixed, I 

6767 static buffer that is big enough to hold most answers (perhaps 512 or 1024 bytes), but then use I 

6768 malloc () to allocate a larger buffer if it finds that this is too small. 

6769 RATIONALE 

6770 Application developers can normally determine any configuration variable by means of reading I 

6771 from the stream opened by a call to: I 

6772 popen ("command -p getconf variable", "r"); I 

6773 The confstr() function with a name argument of _CS_PATH returns a string that can be used as a I 

6774 PATH environment variable setting that will reference the standard shell and utilities as I 

6775 described in the Commands and Utilities volume of IEEE Std. 1003.1-200x. I 

6776 The confstr( ) function copies the returned string into a buffer supplied by the application instead I 

6777 of returning a pointer to a string. This allows a cleaner function in some implementations (such 

6778 as those with lightweight processes) and resolves questions about when the application must 

6779 copy the string returned. 

6780 FUTURE DIRECTIONS 

6781 None. 

6782 SEE ALSO 

6783 pathconf( ), sysconf( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

6784 <unistd.h>, the Commands and Utilities volume of IEEE Std. 1003.1-200x 

6785 CHANGE HISTORY 

6786 First released in Issue 4. 

6787 Derived from the ISO POSIX-2 standard. 
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6788 Issue 5 

6789 A table indicating the permissible values of name are added to the DESCRIPTION. All those 

6790 marked EX are new in this issue. 


6791 Issue 6 

6792 The Open Group corrigenda item U033/7 has been applied. The return value for the case 

6793 returning the size of the buffer now explicitly states that this includes the terminating null. 


6794 The following new requirements on POSIX implementations derive from alignment with the 

6795 Single UNIX Specification: 


6796 

6797 

6798 


• The DESCRIPTION is updated with new arguments which can be used to determine 
configuration strings for C compiler flags, linker/loader flags, and libraries for each different 
supported programming environment. This is a change to support data size neutrality. 


6799 

6800 
6801 


The following changes were made to align with the IEEE P1003.1a draft standard: I 

• The DESCRIPTION is updated to include text describing how _CS_PATH can be used to I 
obtain a PATH to access the standard utilities. I 
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6802 NAME 

6803 connect — connect a socket 

6804 SYNOPSIS 

6805 tinclude <sys/socket. h> 

6806 int connect(int socket, const struct sockaddr * address , 

6807 socklen_t address_len) ; 

6808 DESCRIPTION 

6809 The connect() function requests a connection to be made on a socket. The function takes the 

6810 following arguments: 

6811 socket Specifies the file descriptor associated with the socket. 

6812 address Points to a sockaddr structure containing the peer address. The length and 

6813 format of the address depend on the address family of the socket. 

6814 address_len Specifies the length of the sockaddr structure pointed to by the address 

6815 argument. 

6816 If the socket has not already been bound to a local address, connect ( ) shall bind it to an address 

6817 which, unless the socket's address family is AF_UNIX, is an unused local address. 

6818 If the initiating socket is not connection-mode, then connect ( ) shall set the socket's peer address, 

6819 and no connection is made. For SOCK_DGRAM sockets, the peer address identifies where all 

6820 datagrams are sent on subsequent send( ) functions, and limits the remote sender for subsequent 

6821 recvO functions. If address is a null address for the protocol, the socket's peer address shall be 

6822 reset. 

6823 If the initiating socket is connection-mode, then connectO attempts to establish a connection to 

6824 the address specified by the address argument. 

6825 If the connection cannot be established immediately and 0_NONBLOCK is not set for the file 

6826 descriptor for the socket, connect () shall block for up to an unspecified timeout interval until the 

6827 connection is established. If the timeout interval expires before the connection is established, 

6828 connectO shall fail and the connection attempt shall be aborted. If connectO is interrupted by a 

6829 signal that is caught while blocked waiting to establish a connection, connect () shall fail and set 

6830 errno to [EINTR], but the connection request shall not be aborted, and the connection shall be 

6831 established asynchronously. 

6832 If the connection cannot be established immediately and 0_NONBLOCK is set for the file 

6833 descriptor for the socket, connect () shall fail and set errno to [EINPROGRESS], but the connection 

6834 request shall not be aborted, and the connection shall be established asynchronously. 

6835 Subsequent calls to connect ( ) for the same socket, before the connection is established, shall fail 

6836 and set errno to [EALREADY]. 

6837 When the connection has been established asynchronously, select () and poll () shall indicate that 

6838 the file descriptor for the socket is ready for writing. 

6839 The socket in use may require the process to have appropriate privileges to use the connectO 

6840 function. 

6841 RETURN VALUE 

6842 Upon successful completion, connectO shall return 0; otherwise, -1 shall be returned and errno 

6843 set to indicate the error. 
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6844 ERRORS 


The connect () function shall fail if: 

[EADDRNOTAVAIL] 

The specified address is not available from the local machine. 
[EAFNOSUPPORT] 

The specified address is not a valid address for the address family of the 
specified socket. 

[EALREADY] A connection request is already in progress for the specified socket. 

[EBADF] The socket argument is not a valid file descriptor. 

[ECONNREFUSED] 

The target address was not listening for connections or refused the connection 
request. 

[EFAULT] The address parameter cannot be accessed. 

[EINPROGRESS] 0_N0NBL0CK is set for the file descriptor for the socket and the connection 
cannot be immediately established; the connection shall be established 
asynchronously. 

[EINTR] The attempt to establish a connection was interrupted by delivery of a signal 

that was caught; the connection shall be established asynchronously. 

[EISCONN] The specified socket is connection-mode and is already connected. 

[ENETUNREACH] 

No route to the network is present. 

[ENOTSOCK] The socket argument does not refer to a socket. 

[EPROTOTYPE] The specified address has a different type than the socket bound to the 
specified peer address. 

[ETIMEDOUT] The attempt to connect timed out before a connection was made. 

If the address family of the socket is AF_UNIX, then connect () shall fail if: 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[ELOOP] Too many symbolic links were encountered in translating the path name in 

address. 

[ENAMETOOLONG] 

A component of a path name exceeded |NAME_MAX} characters, or an entire 
path name exceeded {PATH_MAX} characters. 


[ENOENT] 


[ENOTDIR] A component of the path prefix of the path name in address is not a directory. 
The connect () function may fail if: 

[EACCES] Search permission is denied for a component of the path prefix; or write 

access to the named socket is denied. 

[EADDRINUSE] Attempt to establish a connection that uses addresses that are already in use. 
[ECONNRESET] Remote host reset the connection request. 


A component of the path name does not name an existing file or the path 
name is an empty string. 
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6884 [EHOSTUNREACH] 

6885 The destination host cannot be reached (probably because the host is down or 

6886 a remote router cannot reach it). 

6887 [EINVAL] The addressjen argument is not a valid length for the address family; or 

6888 invalid address family in the sockaddr structure. 

6889 [ENAMETOOLONG] 

6890 Path name resolution of a symbolic link produced an intermediate result 

6891 whose length exceeds |PATH_MAX}. 

6892 [ENETDOWN] The local function used to reach the destination is down. 

6893 [ENOBUFS] No buffer space is available. 

6894 xsr [ENOSR] There were insufficient STREAMS resources available to complete the 

6895 operation. 

6896 [EOPNOTSUPP] The socket is listening and cannot be connected. 

6897 EXAMPLES 

6898 None. 

6899 APPLICATION USAGE 

6900 If connect () fails, the state of the socket is unspecified. Portable applications should close the file 

6901 descriptor and create a new socket before attempting to reconnect. 

6902 RATIONALE 

6903 None. 

6904 FUTURE DIRECTIONS 

6905 None. 

6906 SEE ALSO 

6907 accept (), bind(), close(), getsockname(), poll(), select(), send(), shutdown(), socket(), the System 

6908 Interface Definitions volume of IEEE Std. 1003.1-200x, <sys/socket.h> 

6909 CHANGE HISTORY 

6910 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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6911 NAME 

6912 cos — cosine function 

6913 SYNOPSIS 

6914 #include <math.h> 

6915 double cos (double x) ; 

6916 DESCRIPTION 

6917 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

6918 conflict between the requirements described here and the ISO C standard is unintentional. This I 

6919 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

6920 The cos () function shall compute the cosine of x, measured in radians. 

6921 An application wishing to check for error situations should set errno to 0 before calling cos( ). If 

6922 errno is non-zero on return, or the returned value is NaN, an error has occurred. 

6923 RETURN VALUE 

6924 Upon successful completion, cos () shall return the cosine of x. 

6925 xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

6926 xsi If x is ±Inf, either 0 shall be returned and errno set to [EDOM], or NaN shall be returned and errno 

6927 may be set to [EDOM]. 

6928 If the result underflows, 0 shall be returned and errno may be set to [ERANGE]. 

6929 ERRORS 

6930 The cos () function may fail if: 

6931 xsi [EDOM] The value of x is NaN or x is ±Inf. 

6932 [ERANGE] The result underflows 

6933 xsi No other errors shall occur. 

6934 EXAMPLES 

6935 Taking the Cosine of a 45-Degree Angle 

6936 tinclude <math.h> 

6937 

6938 double radians = 45 * M_PI / 180; 

6939 double result; 

6940 

6941 result = cos (radians); 

6942 APPLICATION USAGE 

6943 The cos () function may lose accuracy when its argument is far from 0. 

6944 RATIONALE 

6945 None. 

6946 FUTURE DIRECTIONS 

6947 None. 

6948 SEE ALSO 

6949 acos(), isnan(), sin(), tan(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

6950 <math.h> 
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6951 CHANGE HISTORY 

6952 First released in Issue 1. 

6953 Derived from Issue 1 of the SVID. 

6954 Issue 4 

6955 References to matherr {) are removed. 

6956 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

6957 ISO C standard and to rationalize error handling in the mathematics functions. 

6958 The return value specified for [EDOM] is marked as an extension. 

6959 Issue 5 

6960 The DESCRIPTION is updated to indicate how an application should check for an error. This 

6961 text was previously published in the APPLICATION USAGE section. 
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6962 NAME 

6963 cosh — hyperbolic cosine function 

6964 SYNOPSIS 

6965 #include <math.h> 

6966 double cosh (double x) ; 

6967 DESCRIPTION 

6968 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

6969 conflict between the requirements described here and the ISO C standard is unintentional. This I 

6970 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

6971 The cosh( ) function shall compute the hyperbolic cosine of x. 

6972 An application wishing to check for error situations should set errno to 0 before calling cosh(). If 

6973 errno is non-zero on return, or the returned value is NaN, an error has occurred. 

6974 RETURN VALUE 

6975 Upon successful completion, cosh() shall return the hyperbolic cosine of x. 

6976 If the result would cause an overflow, HUGE_VAL shall be returned and errno set to [ERANGE]. 

6977 xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM]. 

6978 ERRORS 

6979 The cosh () function shall fail if: 

6980 [ERANGE] The result would cause an overflow. 

6981 The cosh () function may fail if: 

6982 xsi [EDOM] The value of x is NaN. 

6983 xsi No other errors shall occur. 

6984 EXAMPLES 

6985 None. 

6986 APPLICATION USAGE 

6987 None. 

6988 RATIONALE 

6989 None. 

6990 FUTURE DIRECTIONS 

6991 None. 

6992 SEE ALSO 

6993 acosh (), isnan (), sink (), tanh (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

6994 <math.h> 

6995 CHANGE HISTORY 

6996 First released in Issue 1. 

6997 Derived from Issue 1 of the SVID. 

6998 Issue 4 

6999 References to matherri ) are removed. 

7000 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

7001 ISO C standard and to rationalize error handling in the mathematics functions. 
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7002 

7003 

7004 

7005 


The return value specified for [EDOM] is marked as an extension. 

Issue 5 

The DESCRIPTION is updated to indicate how an application should check for an error. This 
text was previously published in the APPLICATION USAGE section. 
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7006 NAME 

7007 creat — create a new file or rewrite an existing one 

7008 SYNOPSIS 

7009 oh #include <sys/stat.h> 

7010 tinclude <fcntl.h> 

7011 int creat (const char *path, mode_t mode) ; 

7012 DESCRIPTION 

7013 The function call: 

7014 creat (path, mode) 

7015 is equivalent to: 

7016 open (path, 0_WR0NLY | 0_CREAT | 0_TRUNC, mode) 

7017 RETURN VALUE 

7018 Refer to open(). 

7019 ERRORS 

7020 Refer to open (). 

7021 EXAMPLES 

7022 Creating a File 

7023 The following example creates the file /tmp/file with read and write permissions for the file 

7024 owner and read permission for group and others. The resulting file descriptor is assigned to the 

7025 fd variable. 

7026 tinclude <fcntl.h> 

7027 

7028 int fd; 

7029 mode_t mode = S_IRUSR ! S_IWUSR | S_IRGRP | S_IROTH; 

7030 char *filename = "/tmp/file"; 

7031 

7032 fd = creat (filename, mode); 

7033 

7034 APPLICATION USAGE 

7035 None. 

7036 RATIONALE 

7037 The creat () function is redundant. Its services are also provided by the open() function. It has 

7038 been included primarily for historical purposes since many existing applications depend on it. It 

7039 is best considered a part of the C binding rather than a function that should be provided in other 

7040 languages. 

7041 FUTURE DIRECTIONS 

7042 None. 

7043 SEE ALSO 

7044 open(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <fcntl.h>, <sys/stat.h>, 

7045 <sys/types.h> 
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7046 CHANGE HISTORY 

7047 First released in Issue 1. 

7048 Derived from Issue 1 of the SVID. 

7049 Issue 4 

7050 The <sys/types.h> and <sys/stat.h> headers are now marked as optional (OH); these headers 

7051 need not be included on XSI-conformant systems. 

7052 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

7053 • The type of argument path is changed from char* to const char*. 

7054 Issue 6 

7055 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

7056 The following new requirements on POSIX implementations derive from alignment with the 

7057 Single UNIX Specification: 

7058 • The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 

7059 required for conforming implementations of previous POSIX specifications, it was not 

7060 required for UNIX applications. 
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7061 NAME 

7062 crypt — string encoding function (CRYPT) 

7063 SYNOPSIS 

7064 xsi #include <unistd.h> 

7065 char *crypt (const char *key r const char *salt) ; 

7066 

7067 DESCRIPTION 

7068 The crypt () function is a string encoding function. The algorithm is implementation-dependent. 

7069 The key argument points to a string to be encoded. The salt argument is a string chosen from the 

7070 set: 

7071 abcdefghi jklmnopqrstuvwxyz 

7072 ABCDEFGHIJKLMNOPQRSTUVWXYZ 

7073 0 1 2 3 4 5 6 7 8 9./ 

7074 The first two characters of this string may be used to perturb the encoding algorithm. 

7075 The return value of crypt () points to static data that is overwritten by each call. 

7076 The crypt () function need not be reentrant. A function that is not required to be reentrant is not 

7077 required to be thread-safe. 

7078 RETURN VALUE 

7079 Upon successful completion, crypt () shall return a pointer to the encoded string. The first two 

7080 characters of the returned value are those of the salt argument. Otherwise, it shall return a null 

7081 pointer and set errno to indicate the error. 

7082 ERRORS 

7083 The crypt () function shall fail if: 

7084 [ENOSYS] The functionality is not supported on this implementation. 

7085 EXAMPLES 

7086 Encoding Passwords 

7087 The following example finds a user database entry matching a particular user name and changes 

7088 the current password to a new password. The crypt() function is used to generate an encoded 

7089 version of each password. The first call to crypt() produces an encoded version of the old 

7090 password; that encoded password is then compared to the password stored in the user database. 

7091 The second call to crypt () encodes the new password before it is stored. 

7092 The pntpivent( ) function, used in the following example, is not part of IEEE Std. 1003.1-200x. 

7093 tinclude <unistd.h> 

7094 #include <pwd.h> 

7095 #include <string.h> 

7096 tinclude <stdio.h> 

7097 

7098 int valid_change; 

7099 int pfd; /* Integer for file descriptor returned by open () . */ 

7100 FILE *fpfd; /* File pointer for use in putpwentO . */ 

7101 struct passwd *p; 

7102 char user [100]; 

7103 char oldpasswd [ 100 ] ; 

7104 char newpasswd [ 100 ] ; 
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7 105 char savepasswd [ 100 ] ; 

7106 

7107 valid_change = 0; 

7108 while ( (p = getpwent ()) != NULL) { 

7109 /* Change entry if found. */ 

7110 if (strcmp (p->pw_name, user) == 0) { 

7111 if (strcmp (p->pw_passwd, crypt (oldpasswd, p->pw_passwd) ) == 0) 

7112 strcpy (savepasswd, crypt (newpasswd, user) ) ; 

7113 p->pw_passwd = savepasswd; 

7114 valid_change = 1; 

7115 } 

7116 else { 

7117 fprintf (stderr, "Old password is not valid\n"); 

7118 } 

7119 } 

7120 /* Put passwd entry into ptmp. */ 

7121 putpwent (p, fpfd) ; 

7122 } 

7123 APPLICATION USAGE 

7124 The values returned by this function need not be portable among XSI-conformant systems. 

7125 RATIONALE 

7126 None. 

7127 FUTURE DIRECTIONS 

7128 None. 

7129 SEE ALSO 

7130 encrypt( ), setkey( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

7131 CHANGE HISTORY 

7132 First released in Issue 1. 

7133 Derived from Issue 1 of the SVID. 

7134 Issue 4 

7135 The <unistd.h> header is added to the SYNOPSIS section. 

7136 The type of arguments key and salt are changed from char* to const char*. 

7137 The DESCRIPTION now explicitly defines the characters that can appear in the salt argument. 

7138 Issue 5 

7139 Normative text previously in the APPLICATION USAGE section is moved to the 

7140 DESCRIPTION. 
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7141 NAME 

7142 ctermid — generate a path name for controlling terminal 

7143 SYNOPSIS 

7144 #include <stdio.h> 

7145 char *ctermid (char *s) ; 

7146 DESCRIPTION 

7147 The ctermid () function shall generate a string that, when used as a path name, refers to the 

7148 current controlling terminal for the current process. If ctermid () returns a path name, access to 

7149 the file is not guaranteed. 

7150 If the application uses any of the _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS I 

7151 functions, it shall ensure that the ctermid () function is called with a non-NULL parameter. I 

7152 RETURN VALUE 

7153 If s is a null pointer, the string is generated in an area that may be static (and therefore may be 

7154 overwritten by each call), the address of which shall be returned. Otherwise, s is assumed to 

7155 point to a character array of at least {L_ctermid} bytes; the string is placed in this array and the 

7156 value of s shall be returned. The symbolic constant |L_ctermid) is defined in <stdio.h>, and shall 

7157 have a value greater than 0. 

7158 The ctermid () function shall return an empty string if the path name that would refer to the 

7159 controlling terminal cannot be determined, or if the function is unsuccessful. 

7160 ERRORS 

7161 No errors are defined. 

7162 EXAMPLES 

7163 Determining the Controlling Terminal for the Current Process 

7164 The following example returns a pointer to a string that identifies the controlling terminal for the 

7165 current process. The path name for the terminal is stored in the array pointed to by the ptr 

7166 argument, which has a size of L_ctermid +1 bytes, as indicated by the term argument. 

7167 #include <stdio.h> 

7168 

7169 char term [L_ctermid+1 ] ; 

7170 char *ptr; 

7171 ptr = ctermid (term) ; 

7172 APPLICATION USAGE 

7173 The difference between ctermid() and ttyname() is that ttyname() must be handed a file 

7174 descriptor and return a path of the terminal associated with that file descriptor, while ctermid () 

7175 returns a string (such as " /dev/tty ") that refers to the current controlling terminal if used as a 

7176 path name. 

7177 RATIONALE 

7178 |L_ctermid[ must be defined appropriately for a given implementation and must be greater than 

7179 zero so that array declarations using it are accepted by the compiler. The value includes the 

7180 terminating null byte. 

7181 Portable applications that use threads cannot call ctermid () with NULL as the parameter if either 

7182 _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS is defined. If s is not NULL, the 

7183 ctermid () function generates a string that, when used as a path name, refers to the current 

7184 controlling terminal for the current process. If s is NULL, the return value of ctermid() is 
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7185 undefined. 

7186 If the ctermid () function returns a path name, access to the file is not guaranteed. 

7187 There is no additional burden on the programmer—changing to use a hypothetical thread-safe 

7188 version of ctermid () along with allocating a buffer is more of a burden than merely allocating a 

7189 buffer. Application code should not assume that the returned string is short, as some 

7190 implementations have more than two path name components before reaching a logical device 

7191 name. 

7192 FUTURE DIRECTIONS 

7193 None. 

7194 SEE ALSO 

7195 ttyname( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdio.h> 

7196 CHANGE HISTORY 

7197 First released in Issue 1. 

7198 Derived from Issue 1 of the SVID. 

7199 Issue 4 

7200 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

7201 • The DESCRIPTION and RETURN VALUE sections, though functionally identical to Issue 3, 

7202 are rewritten. 

7203 Issue 5 

7204 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 

7205 Issue 6 

7206 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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7207 NAME 

7208 ctime, ctime_r — convert a time value to date and time string 

7209 SYNOPSIS 

7210 tinclude -ctime. h> 

7211 char *ctime (const time_t * clock) ; 

7212 TSF char *ctime_r (const time_t * clock, char *buf) ; 

7213 

7214 DESCRIPTION 

7215 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

7216 conflict between the requirements described here and the ISO C standard is unintentional. This I 

7217 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

7218 The ctime() function shall convert the time pointed to by clock, representing time in seconds 

7219 since the Epoch, to local time in the form of a string. It is equivalent to: 

7220 asctime (localtime (clock) ) 

7221 cx The asctime(), ctime(), gmtime( ), and localtime() functions return values in one of two static 

7222 objects: a broken-down time structure and an array of char. Execution of any of the functions 

7223 may overwrite the information returned in either of these objects by any of the other functions. 

7224 The ctime () function need not be reentrant. A function that is not required to be reentrant is not 

7225 required to be thread-safe. 

7226 tsf The ctime_r( ) function shall convert the calendar time pointed to by clock to local time in exactly 

7227 the same form as ctime( ) and puts the string into the array pointed to by buf (which contains at 

7228 least 26 bytes) and return buf. 

7229 Unlike ctime( ), the thread-safe version ctime_r( ) is not required to set tzname. 

7230 RETURN VALUE 

7231 The ctime ( ) function shall return the pointer returned by asctime () with that broken-down time 

7232 as an argument. 

7233 tsf Upon successful completion, ctime_r() shall return a pointer to the string pointed to by buf. I 

7234 When an error is encountered, a null pointer shall be returned. 

7235 ERRORS 

7236 No errors are defined. 

7237 EXAMPLES 

7238 None. 

7239 APPLICATION USAGE 

7240 Values for the broken-down time structure can be obtained by calling gmtime() or localtime (). 

7241 The ctime() function is included for compatibility with older implementations, and does not 

7242 support localized date and time formats. Applications should use the strftime() function to 

7243 achieve maximum portability. 

7244 The ctime_r( ) function is thread-safe and shall return values in a user-supplied buffer instead of 

7245 possibly using a static data area that may be overwritten by each call. 

7246 RATIONALE 

7247 None. 
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7248 FUTURE DIRECTIONS 

7249 None. 

7250 SEE ALSO 

7251 asctime (), clock (), difftime(), gmtime( ), localtime (), mktime (), strftime (), strptime (), time( ), utime{ ), 

7252 the System Interface Definitions volume of IEEE Std. 1003.1-200x, <time.h> 

7253 CHANGE HISTORY 

7254 First released in Issue 1. 

7255 Derived from Issue 1 of the SVID. 

7256 Issue 4 

7257 The APPLICATION USAGE section is expanded to describe the time-handling functions 

7258 generally and to refer users to strftime( ), which is a locale-dependent time-handling function. 

7259 The following change is incorporated for alignment with the ISO C standard: 

7260 • The type of argument clock is changed from time_t* to const time_t*. 

7261 Issue 5 

7262 Normative text previously in the APPLICATION USAGE section is moved to the 

7263 DESCRIPTION. 

7264 The ctime_r( ) function is included for alignment with the POSIX Threads Extension. 

7265 A note indicating that the ctime{ ) function need not be reentrant is added to the DESCRIPTION. 

7266 Issue 6 

7267 Extensions beyond the ISO C standard are now marked. 

7268 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 

7269 The APPLICATION USAGE section is updated to include a note on the thread-safe function and 

7270 its avoidance of possibly using a static data area. 
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7271 NAME 

7272 daylight — daylight savings time flag 

7273 SYNOPSIS 

7274 xsi #include <time.h> 

7275 extern int daylight; 

7276 

7277 DESCRIPTION 

7278 Refer to tzset (). 
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7279 NAME 

7280 dbm_clearerr, dbm_close, dbm_delete, dbm_error, dbm_fetch, dbm_firstkey, dbm_nextkey, 

7281 dbm_open, dbm_store — database functions 

7282 SYNOPSIS 

7283 xsi tinclude <ndbm.h> 

7284 

7285 

7286 

7287 

7288 

7289 

7290 

7291 

7292 

7293 

7294 DESCRIPTION 

7295 These functions create, access, and modify a database. 

7296 A datum consists of at least two members, dptr and dsize. The dptr member points to an object 

7297 that is dsize bytes in length. Arbitrary binary data, as well as character strings, may be stored in 

7298 the object pointed to by dptr. 

7299 The database is stored in two files. One file is a directory containing a bit map of keys and has 

7300 .dir as its suffix. The second file contains all data and has .pag as its suffix. 

7301 The dbm_open () function shall open a database. The file argument to the function is the path 

7302 name of the database. The function opens two files named file. dir and file. pag. The open_flags 

7303 argument has the same meaning as th e flags argument of open() except that a database opened 

7304 for write-only access opens the files for read and write access and the behavior of the 

7305 0_APPEND flag is unspecified. The filejnode argument has the same meaning as the third 

7306 argument of open (). 

7307 The dbm_close( ) function shall close a database. The application shall ensure that argument db is I 

7308 a pointer to a dbm structure that has been returned from a call to dbm_open (). I 

7309 The dbmjetch () function shall read a record from a database. The argument db is a pointer to a 

7310 database structure that has been returned from a call to dbm_open(). The argument key is a 

7311 datum that has been initialized by the application to the value of the key that matches the key of I 

7312 the record the program is fetching. 

7313 The dbm_store( ) function shall write a record to a database. The argument db is a pointer to a 

7314 database structure that has been returned from a call to dbm_open{). The argument key is a 

7315 datum that has been initialized by the application to the value of the key that identifies (for I 

7316 subsequent reading, writing, or deleting) the record the application is writing. The argument I 

7317 content is a datum that has been initialized by the application to the value of the record the I 

7318 program is writing. The argument storejnode controls whether dbm_store() replaces any pre- 

7319 existing record that has the same key that is specified by the key argument. The application shall I 

7320 set storejnode to either DBM_INSERT or DBM_REPLACE. If the database contains a record that I 

7321 matches the key argument and storejnode is DBM_REPLACE, the existing record is replaced with 

7322 the new record. If the database contains a record that matches the key argument and storejnode 

7323 is DBM_INSERT, the existing record is left unchanged and the new record ignored. If the 

7324 database does not contain a record that matches the key argument and storejnode is either 

7325 DBM_INSERT or DBM_REPLACE, the new record is inserted in the database. 


int dbm_clearerr(DBM * db ); 

void dbm_close(DBM * db) ; 

int dbm_delete(DBM *db, datum key) ; 

int dbm_error(DBM * db) ; 

datum dbm_fetch(DBM *db, datum key); 

datum dbm_firstkey(DBM *db) ; 

datum dbm_nextkey(DBM * db) ; 

DBM *dbm_open(const char *file, int open_flags, mode_t filejnode) ; 
int dbm_store(DBM *db, datum key, datum content, int storejnode) ; 
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7326 The application shall ensure that the sum of the sizes of a key/content pair does not exceed the I 

7327 internal block size. Moreover, the application shall ensure that all key/content pairs that hash I 

7328 together fit on a single block. The dbm_store( ) function shall return an error in the event that a I 

7329 disk block fills with inseparable data. 

7330 The dbm_delete( ) function shall delete a record and its key from the database. The argument db is 

7331 a pointer to a database structure that has been returned from a call to dbm_open (). The argument 

7332 key is a datum that has been initialized by the application to the value of the key that identifies I 

7333 the record the program is deleting. 

7334 The dbm_firstkey{) function shall return the first key in the database. The argument db is a 

7335 pointer to a database structure that has been returned from a call to dbm_open (). 

7336 The dbm_nextkey() function shall return the next key in the database. The argument db is a 

7337 pointer to a database structure that has been returned from a call to dbm_open( ). The application I 

7338 shall ensure that the dbm_firstkey() function is called before calling dbm_nextkey(). Subsequent I 

7339 calls to dbm_nextkey( ) return the next key until all of the keys in the database have been 

7340 returned. 

7341 The dbm_error( ) function shall return the error condition of the database. The argument db is a 

7342 pointer to a database structure that has been returned from a call to dbm_open (). 

7343 The dbm_clearerr( ) function shall clear the error condition of the database. The argument db is a 

7344 pointer to a database structure that has been returned from a call to dbm_open (). 

7345 These database functions shall support key/content pairs of at least 1023 bytes. 

7346 The dptr pointers returned by these functions may point into static storage that may be changed 

7347 by subsequent calls. 

7348 These functions need not be reentrant. A function that is not required to be reentrant is not 

7349 required to be thread-safe. 

7350 RETURN VALUE 

7351 The dbm_store() and dbm_delete() functions shall return 0 when they succeed and a negative 

7352 value when they fail. 

7353 The dbm_store{ ) function shall return 1 if it is called with a flags value of DBM_INSERT and the 

7354 function finds an existing record with the same key. 

7355 The dbm_error( ) function shall return 0 if the error condition is not set and return a non-zero 

7356 value if the error condition is set. 

7357 The return value of dbm_clearerr( ) is unspecified. 

7358 The dbm jirstkeyt ) and dbm_nextkey ( ) functions shall return a key datum. When the end of the 

7359 database is reached, the dptr member of the key is a null pointer. If an error is detected, the dptr 

7360 member of the key shall be a null pointer and the error condition of the database shall be set. 

7361 The dbmjetch () function shall return a content datum. If no record in the database matches the 

7362 key or if an error condition has been detected in the database, the dptr member of the content 

7363 shall be a null pointer. 

7364 The dbm_open () function shall return a pointer to a database structure. If an error is detected 

7365 during the operation, dbm_open () shall return a (DBM*)0. 

7366 ERRORS 

7367 No errors are defined. 
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7368 EXAMPLES 

7369 None. 

7370 APPLICATION USAGE 

7371 The following code can be used to traverse the database: 

7372 for(key = dbm_firstkey(db); key.dptr != NULL; key = dbm_nextkey(db) ) 

7373 The dbm_ functions provided in this library should not be confused in any way with those of a 

7374 general-purpose database management system. These functions do not provide for multiple 

7375 search keys per entry, they do not protect against multi-user access (in other words they do not 

7376 lock records or files), and they do not provide the many other useful database functions that are 

7377 found in more robust database management systems. Creating and updating databases by use of 

7378 these functions is relatively slow because of data copies that occur upon hash collisions. These 

7379 functions are useful for applications requiring fast lookup of relatively static information that is 

7380 to be indexed by a single key. 

7381 The dbm_delete( ) function need not physically reclaim file space, although it does make it 

7382 available for reuse by the database. 

7383 After calling dbm_store() or dbm_delete() during a pass through the keys by dbmJirstkeyO and 

7384 dbm_nextkey (), the application should reset the database by calling dbm_firstkey() before again 

7385 calling dbm_nextkey( ). The contents of these files are unspecified and may not be portable. 

7386 RATIONALE 

7387 None. 

7388 FUTURE DIRECTIONS 

7389 None. 

7390 SEE ALSO 

7391 open(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <ndbm.h> 

7392 CHANGE HISTORY 

7393 First released in Issue 4, Version 2. 

7394 Issue 5 

7395 Moved from X/OPEN UNIX extension to BASE. 

7396 Normative text previously in the APPLICATION USAGE section is moved to the 

7397 DESCRIPTION. 

7398 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 

7399 Issue 6 

7400 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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7401 NAME 

7402 difftime — compute the difference between two calendar time values 

7403 SYNOPSIS 

7404 #include <time.h> 

7405 double difftime (time_t timel, time_t timeO) ; 

7406 DESCRIPTION 

7407 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

7408 conflict between the requirements described here and the ISO C standard is unintentional. This I 

7409 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

7410 The difftime () function shall compute the difference between two calendar times (as returned by 

7411 time ()): timel-timeO. 

7412 RETURN VALUE 

7413 The difftime () function shall return the difference expressed in seconds as a type double. 

7414 ERRORS 

7415 No errors are defined. 

7416 EXAMPLES 

7417 None. 

7418 APPLICATION USAGE 

7419 None. 

7420 RATIONALE 

7421 None. 

7422 FUTURE DIRECTIONS 

7423 None. 

7424 SEE ALSO 

7425 asctime(), clock(), ctime(), gmtime(), localtime(), mktime( ), strftime(), strptime(), time(), utime{), 

7426 the System Interface Definitions volume of IEEE Std. 1003.1-200x, <time.h> 

7427 CHANGE HISTORY 

7428 First released in Issue 4. 

7429 Derived from the ISO C standard. 
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7430 NAME 

7431 dirname — report the parent directory name of a file path name 

7432 Notes to Reviewers 

7433 This section zvith side shading will not appear in the final copy. - Ed. 

7434 This function or these functions are recommended to become mandatory parts of POSIX.l in the 

7435 next draft. 

7436 SYNOPSIS 

7437 xsi tinclude <libgen.h> 

7438 char *dirname (char *path) ; 

7439 

7440 DESCRIPTION 

7441 The dirname ( ) function shall take a pointer to a character string that contains a path name, and 

7442 return a pointer to a string that is a path name of the parent directory of that file. Trailing ' /' 

7443 characters in the path are not counted as part of the path. 

7444 If path does not contain a ' /', then dirname () shall return a pointer to the string ".". If path is a 

7445 null pointer or points to an empty string, dirname( ) shall return a pointer to the string " . ". 

7446 The dirname( ) function need not be reentrant. A function that is not required to be reentrant is 

7447 not required to be thread-safe. 

7448 RETURN VALUE 

7449 The dirnamei ) function shall return a pointer to a string that is the parent directory of path . If 

7450 path is a null pointer or points to an empty string, a pointer to a string " . " is returned. 

7451 The dirnamei ) function may modify the string pointed to by path, and may return a pointer to 

7452 static storage that may then be overwritten by subsequent calls to dirname (). 

7453 ERRORS 

7454 No errors are defined. 

7455 EXAMPLES 

7456 The following code fragment reads a path name, changes the current working directory to the 

7457 parent directory, and opens the file. 

7458 char path [MAXPATHLEN] , *pathcopy; 

7459 int fd; 

7460 fgets (path, MAXPATHLEN, stdin) ; 

7461 pathcopy = strdup (path) ; 

7462 chdir (dirname (pathcopy) ) ; 

7463 fd = open (basename (path) , 0_RD0NLY) ; 

7464 Sample Input and Output Strings for dirnamei) 

7465 In the following table, the input string is the value pointed to by path , and the output string is 

7466 the return value of the dirnamei ) function. 
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7467 


7468 

Input String 

Output String 

7469 

"/usr/lib" 

"/usr" 

7470 

"/usr/" 


7471 

"usr" 


7472 

If j II 


7473 

II II 


7474 

II II 



7475 Changing the Current Directory to the Parent Directory 

7476 The following program fragment reads a path name, changes the current working directory to 

7477 the parent directory, and opens the file. 

7478 #include <unistd.h> 

7479 #include <limits.h> 

7480 #include <stdio.h> 

7481 tinclude <fcntl.h> 

7482 #include <string.h> 

7483 #include <libgen.h> 

7484 

7485 char path [PATH_MAX] , *pathcopy; 

7486 int fd; 

7487 

7488 fgets (path, PATH_MAX, stdin) ; 

7489 pathcopy = strdup (path) ; 

7490 chdir (dirname (pathcopy) ) ; 

7491 fd = open (basename (path) , 0_RD0NLY) ; 

7492 APPLICATION USAGE 

7493 The dirname () and basename() functions together yield a complete path name. The expression 

7494 dirnameipath) obtains the path name of the directory where basename (path) is found. 

7495 Since the meaning of the leading "//" is implementation-dependent, the dirname( ) //too could 

7496 return either " / / " or ' /' and nothing else. 

7497 RATIONALE 

7498 None. 

7499 FUTURE DIRECTIONS 

7500 None. 

7501 SEE ALSO 

7502 basename( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <libgen.h> 

7503 CHANGE HISTORY 

7504 First released in Issue 4, Version 2. 

7505 Issue 5 

7506 Moved from X/OPEN UNIX extension to BASE. 

7507 Normative text previously in the APPLICATION USAGE section is moved to the 

7508 DESCRIPTION. 

7509 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 
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7510 NAME 

7511 div — compute the quotient and remainder of an integer division 

7512 SYNOPSIS 

7513 tinclude <stdlib.h> 

7514 div_t div(int numer, int denom) ; 

7515 DESCRIPTION 

7516 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

7517 conflict between the requirements described here and the ISO C standard is unintentional. This I 

7518 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

7519 The div () function shall compute the quotient and remainder of the division of the numerator 

7520 numer by the denominator denom. If the division is inexact, the resulting quotient is the integer 

7521 of lesser magnitude that is the nearest to the algebraic quotient. If the result cannot be 

7522 represented, the behavior is undefined; otherwise, quot*denom+rem shall equal numer. 

7523 RETURN VALUE 

7524 The div() function shall return a structure of type div_t, comprising both the quotient and the 

7525 remainder. The structure includes the following members, in any order: 

7526 int quot; /* quotient */ 

7527 int rem; /* remainder */ 

7528 ERRORS 

7529 No errors are defined. 

7530 EXAMPLES 

7531 None. 

7532 APPLICATION USAGE 

7533 None. 

7534 RATIONALE 

7535 None. 

7536 FUTURE DIRECTIONS 

7537 None. 

7538 SEE ALSO 

7539 ldiv( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

7540 CHANGE HISTORY 

7541 First released in Issue 4. 

7542 Derived from the ISO C standard. 
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7543 NAME 

7544 dlclose — close a dlopen () object 

7545 SYNOPSIS 

7546 xsi tinclude <dlfcn.h> 

7547 int dlclose (void *handle) ; 

7548 

7549 DESCRIPTION 

7550 The dlclose () function is used to inform the system that the object referenced by a handle returned 

7551 from a previous dlopen () invocation is no longer needed by the application. 

7552 The use of dlclose () reflects a statement of intent on the part of the process, but does not create 

7553 any requirement upon the implementation, such as removal of the code or symbols referenced 

7554 by handle. Once an object has been closed using dlclose() an application should assume that its 

7555 symbols are no longer available to dlsym(). All objects loaded automatically as a result of 

7556 invoking dlopen () on the referenced object are also closed if this is the last reference to it. 

7557 Although a dlclose () operation is not required to remove structures from an address space, 

7558 neither is an implementation prohibited from doing so. The only restriction on such a removal is 

7559 that no object shall be removed to which references have been relocated, until or unless all such 

7560 references are removed. For instance, an object that had been loaded with a dlopen () operation 

7561 specifying the RTLD_GLOBAL flag might provide a target for dynamic relocations performed in 

7562 the processing of other objects—in such environments, an application may assume that no 

7563 relocation, once made, shall be undone or remade unless the object requiring the relocation has 

7564 itself been removed. 

7565 RETURN VALUE 

7566 If the referenced object was successfully closed, dlclose () shall return 0. If the object could not be 

7567 closed, or if handle does not refer to an open object, dlclose () shall return a non-zero value. More 

7568 detailed diagnostic information shall be available through dlerror (). 

7569 ERRORS 

7570 No errors are defined. 

7571 EXAMPLES 

7572 The following example illustrates use of dlopen () and dlclose (): 

7573 

7574 /* Open a dynamic library and then close it ... */ 

7575 tinclude <dlfcn.h> 

7576 void *mylib; 

7577 int eret; 

7578 mylib = dlopen ( "mylib . so . 1" , RTLD_LAZY) ; 

7579 

7580 eret = dlclose (mylib) ; 

7581 

7582 APPLICATION USAGE 

7583 A portable application should employ a handle returned from a dlopen () invocation only within a 

7584 given scope bracketed by the dlopen () and dlclose () operations. Implementations are free to use 

7585 reference counting or other techniques such that multiple calls to dlopen () referencing the same 

7586 object may return the same object for handle. Implementations are also free to reuse a handle. 

7587 For these reasons, the value of a handle must be treated as an opaque object by the application, 

7588 used only in calls to dlsym () and dlclose (). 
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7589 RATIONALE 

7590 None. 

7591 FUTURE DIRECTIONS 

7592 None. 

7593 SEE ALSO 

7594 dlerror(), dlopen(), dlsym (), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

7595 <dlfcn.h> 

7596 CHANGE HISTORY 

7597 First released in Issue 5. 

7598 Issue 6 

7599 The DESCRIPTION is updated to say that the referenced object is closed "if this is the last 

7600 reference to it". 
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7601 NAME 

7602 dlerror — get diagnostic information 

7603 SYNOPSIS 

7604 xsi #include <dlfcn.h> 

7605 char *dlerror (void) ; 

7606 

7607 DESCRIPTION 

7608 The dlerror( ) function shall return a null-terminated character string (with no trailing <newline>) 

7609 that describes the last error that occurred during dynamic linking processing. If no dynamic 

7610 linking errors have occurred since the last invocation of dlerror( ), dlerror( ) shall return NULL. 

7611 Thus, invoking dlerror( ) a second time, immediately following a prior invocation, shall result in 

7612 NULL being returned. 

7613 The dlerror () function need not be reentrant. A function that is not required to be reentrant is not 

7614 required to be thread-safe. 

7615 RETURN VALUE 

7616 If successful, dlerror( ) shall return a null-terminated character string; otherwise, NULL shall be 

7617 returned. 

7618 ERRORS 

7619 No errors are defined. 

7620 EXAMPLES 

7621 The following example prints out the last dynamic linking error: 

7622 

7623 #include <dlfcn.h> 

7624 char *errstr; 

7625 errstr = dlerror (); 

7626 if (errstr != NULL) 

7627 printf ("A dynamic linking error occurred: (%s)\n", errstr); 

7628 

7629 APPLICATION USAGE 

7630 The messages returned by dlerror( ) may reside in a static buffer that is overwritten on each call 

7631 to dlerror(). Application code should not write to this buffer. Programs wishing to preserve an 

7632 error message should make their own copies of that message. Depending on the application 

7633 environment with respect to asynchronous execution events, such as signals or other 

7634 asynchronous computation sharing the address space, portable applications should use a critical 

7635 section to retrieve the error pointer and buffer. 

7636 RATIONALE 

7637 None. 

7638 FUTURE DIRECTIONS 

7639 None. 

7640 SEE ALSO 

7641 dlclose(), dlopen(), dlsym (), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

7642 <dlfcn.h> 
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7643 CHANGE HISTORY 

7644 First released in Issue 5. 

7645 Issue 6 

7646 In the DESCRIPTION the note about reentrancy and thread-safety is added. 
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7647 NAME 

7648 dlopen — gain access to an executable object file 

7649 SYNOPSIS 

7650 xsi #include <dlfcn.h> 

7651 void *dlopen(const char *file, int mode); 

7652 


7653 DESCRIPTION 

7654 The dlopen () function shall make an executable object file specified by file available to the calling 

7655 program. The class of files eligible for this operation and the manner of their construction are 

7656 specified by the implementation, though typically such files are executable objects such as 

7657 shared libraries, relocatable files, or programs. Note that some implementations permit the 

7658 construction of dependencies between such objects that are embedded within files. In such 

7659 cases, a dlopen () operation shall load such dependencies in addition to the object referenced by 

7660 file. Implementations may also impose specific constraints on the construction of programs that 

7661 can employ dlopen () and its related services. 

7662 A successful dlopen () shall return a handle which the caller may use on subsequent calls to 

7663 dlsym () and dlclose( ). The value of this handle should not be interpreted in any way by the caller. 

7664 file is used to construct a path name to the object file. If file contains a slash character, the file 

7665 argument is used as the path name for the file. Otherwise, file is used in an implementation- 

7666 dependent manner to yield a path name. 

7667 If the value of file is 0, dlopen () shall provide a handle on a global symbol object. This object 

7668 provides access to the symbols from an ordered set of objects consisting of the original program 

7669 image file, together with any objects loaded at program start-up as specified by that process I 

7670 image file (for example, shared libraries), and the set of objects loaded using a dlopen () operation 

7671 together with the RTLD_GLOBAL flag. As the latter set of objects can change during execution, 

7672 the set identified by handle can also change dynamically. 

7673 Only a single copy of an object file is brought into the address space, even if dlopen () is invoked 

7674 multiple times in reference to the file, and even if different path names are used to reference the 

7675 file. 


7676 The mode parameter describes how dlopen () shall operate upon file with respect to the processing 

7677 of relocations and the scope of visibility of the symbols provided within file. When an object is 

7678 brought into the address space of a process, it may contain references to symbols whose 

7679 addresses are not known until the object is loaded. These references shall be relocated before the I 

7680 symbols can be accessed. The mode parameter governs when these relocations take place and I 

7681 may have the following values: 


7682 

7683 

7684 

7685 

7686 

7687 

7688 

7689 


RTLD_LAZY Relocations shall be performed at an implementation-dependent time, 

ranging from the time of the dlopen () call until the first reference to a 
given symbol occurs. Specifying RTLD_LAZY should improve 
performance on implementations supporting dynamic symbol binding as 
a process may not reference all of the functions in any given object. And, 
for systems supporting dynamic symbol resolution for normal process 
execution, this behavior mimics the normal handling of process 
execution. 


7690 

7691 

7692 

7693 


RTLD_NOW All necessary relocations shall be performed when the object is first 

loaded. This may waste some processing if relocations are performed for 
functions that are never referenced. This behavior may be useful for 
applications that need to know as soon as an object is loaded that all 
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7694 symbols referenced during execution shall be available. 

7695 Any object loaded by dlopen () that requires relocations against global symbols can reference the 

7696 symbols in the original process image file, any objects loaded at program start-up, from the I 

7697 object itself as well as any other object included in the same dlopen () invocation, and any objects I 

7698 that were loaded in any dlopen () invocation and which specified the RTLD_GLOBAL flag. To 

7699 determine the scope of visibility for the symbols loaded with a dlopen () invocation, the mode 

7700 parameter should be a bitwise-inclusive OR with one of the following values: 


7701 

7702 

7703 


RTLD_GLOBAL The object's symbols shall be made available for the relocation processing 
of any other object. In addition, symbol lookup using dlopen(0, mode) and 
an associated dlsym () allows objects loaded with this mode to be searched. 


7704 RTLD_LOCAL The object's symbols shall not be made available for the relocation 

7705 processing of any other object. 


7706 If neither RTLD_GLOBAL nor RTLD_LOCAL are specified, then an implementation-dependent 

7707 default behavior shall be applied. 

7708 If a file is specified in multiple dlopen () invocations, mode is interpreted at each invocation. Note, 

7709 however, that once RTLD_NOW has been specified all relocations shall have been completed 

7710 rendering further RTLD_NOW operations redundant and any further RTLD_LAZY operations 

7711 irrelevant. Similarly, note that once RTLD_GLOBAL has been specified the object shall maintain 

7712 the RTLD_GLOBAL status regardless of any previous or future specification of RTLD_LOCAL, 

7713 as long as the object remains in the address space (see dlclose ()). 


7714 Symbols introduced into a program through calls to dlopen () may be used in relocation 

7715 activities. Symbols so introduced may duplicate symbols already defined by the program or 

7716 previous dlopen () operations. To resolve the ambiguities such a situation might present, the 

7717 resolution of a symbol reference to symbol definition is based on a symbol resolution order. Two 

7718 such resolution orders are defined: load or dependency ordering. Load order establishes an 

7719 ordering among symbol definitions, such that the definition first loaded (including definitions 

7720 from the image file and any dependent objects loaded with it) has priority over objects added 

7721 later (via dlopen ()). Load ordering is used in relocation processing. Dependency ordering uses a 

7722 breadth-first order starting with a given object, then all of its dependencies, then any dependents 

7723 of those, iterating until all dependencies are satisfied. With the exception of the global symbol 

7724 object obtained via a dlopen () operation on a file of 0, dependency ordering is used by the 

7725 dlsym () function. Load ordering is used in dlsym () operations upon the global symbol object. 


7726 When an object is first made accessible via dlopen () it and its dependent objects are added in 

7727 dependency order. Once all the objects are added, relocations are performed using load order. 

7728 Note that if an object or its dependencies had been previously loaded, the load and dependency 

7729 orders may yield different resolutions. 


7730 The symbols introduced by dlopen () operations, and available through dlsym () are at a 

7731 minimum those which are exported as symbols of global scope by the object. Typically such 

7732 symbols shall be those that were specified in (for example) C source code as having extern 

7733 linkage. The precise manner in which an implementation constructs the set of exported symbols 

7734 for a dlopen () object is specified by that implementation. 


7735 RETURN VALUE 

7736 If file cannot be found, cannot be opened for reading, is not of an appropriate object format for 

7737 processing by dlopen (), or if an error occurs during the process of loading file or relocating its 

7738 symbolic references, dlopen () shall return NULL. More detailed diagnostic information shall be 

7739 available through dierror (). 
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7740 ERRORS 

7741 No errors are defined. 

7742 EXAMPLES 

7743 None. 

7744 APPLICATION USAGE 

7745 None. 

7746 RATIONALE 

7747 None. 

7748 FUTURE DIRECTIONS 

7749 None. 

7750 SEE ALSO 

7751 dlclose(), dlerror(), dlsym(), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

7752 <dlfcn.h> 

7753 CHANGE HISTORY 

7754 First released in Issue 5. 
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7755 NAME 

7756 dlsym — obtain the address of a symbol from a dlopen () object 

7757 SYNOPSIS 

7758 xsi #include <dlfcn.h> 

7759 void *dlsym(void * handle, const char * name) ; 

7760 

7761 DESCRIPTION 

7762 The dlsym () function allows a process to obtain the address of a symbol defined within an object 

7763 made accessible through a dlopen () call, handle is the value returned from a call to dlopen () (and 

7764 which has not since been released via a call to diclose ()), and name is the symbol's name as a 

7765 character string. 

7766 The dlsym () function shall search for the named symbol in all objects loaded automatically as a 

7767 result of loading the object referenced by handle (see dlopen ()). Load ordering is used in dlsym() 

7768 operations upon the global symbol object. The symbol resolution algorithm used shall be 

7769 dependency order as described in dlopen (). 

7770 The RTLD_NEXT flag is reserved for future use. 

7771 RETURN VALUE 

7772 If handle does not refer to a valid object opened by dlopen (), or if the named symbol cannot be 

7773 found within any of the objects associated with handle, dlsym () shall return NULL. More 

7774 detailed diagnostic information shall be available through dlerror (). 

7775 ERRORS 

7776 No errors are defined. 

7777 EXAMPLES 

7778 The following example shows how dlopen () and dlsym () can be used to access either function or 

7779 data objects. For simplicity, error checking has been omitted. 

7780 void *handle; 

7781 int *iptr, (*fptr) (int); 

7782 /* open the needed object */ 

7783 handle = dlopen("/usr/home/me/libfoo.so.1", RTLD_LAZY); 

7784 /* find the address of function and data objects */ 

7785 fptr = (int (*) (int)) dlsym (handle, "my_function" ) ; 

7786 iptr = (int *) dlsym (handle, "my_ob ject" ) ; 

7787 /* invoke function, passing value of integer as a parameter */ 

7788 (*fptr) (*iptr) ; 

7789 APPLICATION USAGE 

7790 Special purpose values for handle are reserved for future use. These values and their meanings 

7791 are: 

7792 

7793 

7794 

7795 

7796 

7797 

7798 
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RTLD_NEXT Specifies the next object after this one that defines name. This one refers to the 
object containing the invocation of dlsym (). The next object is the one found 
upon the application of a load order symbol resolution algorithm (see 
dlopen ()). The next object is either one of global scope (because it was 
introduced as part of the original process image or because it was added with 
a dlopen () operation including the RTLD_GLOBAL flag), or is an object that 
was included in the same dlopen () operation that loaded this one. 
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7799 

7800 

7801 

7802 

7803 

7804 

7805 RATIONALE 

7806 None. 

7807 FUTURE DIRECTIONS 

7808 None. 

7809 SEE ALSO 

7810 dlclose(), dlerror(), dlopen (), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

7811 <dlfcn.h> 

7812 CHANGE HISTORY 

7813 First released in Issue 5. 


The RTLD_NEXT flag is useful to navigate an intentionally created hierarchy 
of multiply-defined symbols created through interposition. For example, if a 
program wished to create an implementation of malloc () that embedded some 
statistics gathering about memory allocations, such an implementation could 
use the real malloc() definition to perform the memory allocation—and itself 
only embed the necessary logic to implement the statistics gathering function. 
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7814 NAME 

7815 drand48, erand48, jrand48, lcong48, lrand48, mrand48, nrand48, seed48, srand48 — generate 

7816 uniformly distributed pseudo-random numbers 

7817 SYNOPSIS 

7818 xsi tinclude <stdlib.h> 

7819 double drand4 8 (void) ; 

7820 double erand48 (unsigned short int xsubi[3]); 

7821 long int jrand48 (unsigned short int xsufoi[3]); 

7822 void lcong48 (unsigned short int param[l])} 

7823 long int lrand48 (void) ; 

7824 long int mrand48 (void) ; 

7825 long int nrand48 (unsigned short int xsubi[3]); 

7826 unsigned short int *seed48(unsigned short int seedl6v[ 3]) ; 

7827 void srand48(long int seedval) ; 

7828 


7829 DESCRIPTION 

7830 This family of functions generates pseudo-random numbers using a linear congruential 

7831 algorithm and 48-bit integer arithmetic. 

7832 The dmnd48() and ercind48 () functions shall return non-negative, double-precision, floating- 

7833 point values, uniformly distributed over the interval [0.0,1.0). 

7834 The lmnd48() and nmnd48() functions shall return non-negative, long integers, uniformly 

7835 distributed over the interval [0,2 31 ). 


7836 

7837 


The mrand48 () and jrand48 () functions shall return signed long integers uniformly distributed 
over the interval [-2' 1 ,2 31 ). 


7838 The srand48 (), seed48 (), and lcong48 () are initialization entry points, one of which should be 

7839 invoked before either dmnd48(), lrand48(), or mrand48 () is called. (Although it is not 

7840 recommended practice, constant default initializer values shall be supplied automatically if 

7841 drand48(), lrand48(), or mrand48 () is called without a prior call to an initialization entry point.) 

7842 The erand48 (), nrand48{), and jrand48() functions do not require an initialization entry point to 

7843 be called first. 


7844 All the routines work by generating a sequence of 48-bit integer values, X„ according to the 

7845 linear congruential formula: 

7846 X n+ i — {ttX n + C ) nUK ] m H — 0 

7847 The parameter m = 2 48 ; hence 48-bit integer arithmetic is performed. Unless lcong48() is invoked, 

7848 the multiplier value a and the addend value c are given by: 

7849 a = 5DEECE66D 16 = 273673163155 8 

7850 c = B 16 = 13 8 

7851 The value returned by any of the drand48(), erand48(), jmnd48(), lrand48(), mrand48 (), or 

7852 nrand48() functions is computed by first generating the next 48-bit X, in the sequence. Then the 

7853 appropriate number of bits, according to the type of data item to be returned, are copied from 

7854 the high-order (leftmost) bits of X, and transformed into the returned value. 

7855 The drand48(), lrand48(), and mrand48 () functions store the last 48-bit X,- generated in an 

7856 internal buffer; that is why the application shall ensure that these are initialized prior to being I 

7857 invoked. The erand48(), nrand48 ( ), and jrand48() functions require the calling program to I 

7858 provide storage for the successive X, values in the array specified as an argument when the 
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7859 functions are invoked. That is why these routines do not have to be initialized; the calling 

7860 program merely has to place the desired initial value of X, into the array and pass it as an 

7861 argument. By using different arguments, erand48(), nrand48(), and jmnd48() allow separate 

7862 modules of a large program to generate several independent streams of pseudo-random numbers; 

7863 that is, the sequence of numbers in each stream shall not depend upon how many times the 

7864 routines are called to generate numbers for the other streams. 

7865 The initializer function srand48() sets the high-order 32 bits of X, to the low-order 32 bits 

7866 contained in its argument. The low-order 16 bits of X, are set to the arbitrary value 330E 16 . 

7867 The initializer function seed48( ) sets the value of X, to the 48-bit value specified in the argument 

7868 array. The low-order 16 bits of X, are set to the low-order 16 bits of seedl6v[0]. The mid-order 16 

7869 bits of X, are set to the low-order 16 bits of seedl6v[l ]. The high-order 16 bits of X, are set to the 

7870 low-order 16 bits of seedl6v[2]. In addition, the previous value of X, is copied into a 48-bit 

7871 internal buffer, used only by seed48(), and a pointer to this buffer is the value returned by 

7872 seed48 (). This returned pointer, which can just be ignored if not needed, is useful if a program is 

7873 to be restarted from a given point at some future time—use the pointer to get at and store the 

7874 last X, value, and then use this value to re-initialize via seed48 () when the program is restarted. 

7875 The initializer function lcong48 () allows the user to specify the initial X„ the multiplier value a, 

7876 and the addend value c. Argument array elements param[0-2] specify X„ pamm[3-5] specify the 

7877 multiplier a, and param[6] specifies the 16-bit addend c. After lcong48() is called, a subsequent 

7878 call to either srand48( ) or seed48 () shall restore the standard multiplier and addend values, a and 

7879 c, specified above. 

7880 The dmnd48(), lrand48{), and mrand48{) functions need not be reentrant. A function that is not 

7881 required to be reentrant is not required to be thread-safe. 

7882 RETURN VALUE 

7883 As described in the DESCRIPTION above. 

7884 ERRORS 

7885 No errors are defined. 

7886 EXAMPLES 

7887 None. 

7888 APPLICATION USAGE 

7889 None. 

7890 RATIONALE 

7891 None. 

7892 FUTURE DIRECTIONS 

7893 None. 

7894 SEE ALSO 

7895 rand{), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

7896 CHANGE HISTORY 

7897 First released in Issue 1. 

7898 Derived from Issue 1 of the SVID. 

7899 Issue 4 

7900 The type long is replaced by long int and the type unsigned short is replaced by unsigned short 

7901 int in the SYNOPSIS section. 

7902 In the DESCRIPTION, the description of smnd48() is amended to fix a limitation in Issue 3, 

7903 which indicates that the high-order 32 bits of X, are set to the |LONG_BIT[ bits in the argument. 
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7904 Though unintentional, the implication of this statement is that |LONG_BIT) would be 32 on all 

7905 systems compliant with Issue 3, when in fact Issue 3 imposes no such restriction. 

7906 The <stdlib.h> header is added to the SYNOPSIS section. 

7907 The argument list for the lrand48 () and mrand48 () functions now contains void. 

7908 Issue 5 

7909 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 

7910 Issue 6 

7911 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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7912 NAME 

7913 dup, dup2 — duplicate an open file descriptor 

7914 SYNOPSIS 

7915 tinclude <unistd.h> 

7916 int dup(int fildes); 

7917 int dup2 (int fildes, int fildes2) ; 

7918 DESCRIPTION 

7919 The dnp() and dup2 () functions provide an alternative interface to the service provided by 

7920 fcntl () using the F_DUPFD command. The call: 

7921 fid = dup (fildes) ; 

7922 is equivalent to: 

7923 fid = fcntl ( fildes, F_DUPFD, 0); 

7924 The call: 

7925 fid = dup2 {fildes, fildes2) ; 

7926 is equivalent to: 

7927 close ( fildes2) ; 

7928 fid = fcntl (fildes, F_DUPFD, fildes2) ; 

7929 except for the following: 

7930 • ltfildes2 is less than 0 or greater than or equal to |OPEN_MAX}, dnp2() shall return -1 with 

7931 errno set to [EBADF]. 

7932 • If fildes is a valid file descriptor and is equal to fildes2, dup2 () shall return fildes2 without 

7933 closing it. 

7934 • If fildes is not a valid file descriptor, dnp2 () shall return -1 and shall not clos efildes2. 

7935 • The value returned shall be equal to the value of fildes2 upon successful completion, or -1 

7936 upon failure. 

7937 RETURN VALUE 

7938 Upon successful completion a non-negative integer, namely the file descriptor, shall be returned; 

7939 otherwise, -1 shall be returned and errno set to indicate the error. 

7940 ERRORS 

7941 The dnp( ) function shall fail if: 

7942 [EBADF] The fildes argument is not a valid open file descriptor. 

7943 [EMFILE] The number of file descriptors in use by this process would exceed 

7944 {OPEN_MAX}. 

7945 The dnp2 () function shall fail if: 

7946 [EBADF] The fildes argument is not a valid open file descriptor or the argument fildes2 is 

7947 negative or greater than or equal to [OPEN_MAX[. 

7948 [EINTR] The dnp2 () function was interrupted by a signal. 
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7949 EXAMPLES 

7950 Redirecting Standard Output to a File 

7951 The following example closes standard output for the current processes, re-assigns standard 

7952 output to go to the file referenced by pfd, and closes the original file descriptor to clean up. 

7953 #include <unistd.h> 

7954 

7955 int pfd; 

7956 

7957 close (1) ; 

7958 dup (pfd) ; 

7959 close (pfd) ; 

7960 

7961 Redirecting Error Messages 

7962 The following example redirects messages from stderr to stdont. 

7963 tinclude <unistd.h> 

7964 

7965 dup2 (1, 2); 

7966 

7967 APPLICATION USAGE 

7968 None. 

7969 RATIONALE 

7970 The dnp() and dnp2{) functions are redundant. Their services are also provided by the fcntl ( ) 

7971 function. They have been included in this volume of IEEE Std. 1003.1-200x primarily for 

7972 historical reasons, since many existing applications use them. 

7973 While the brief code segment shown is very similar in behavior to dnp2(), a conforming 

7974 implementation based on other functions defined in this volume of IEEE Std. 1003.1-200x is 

7975 significantly more complex. Least obvious is the possible effect of a signal-catching function that 

7976 could be invoked between steps and allocate or deallocate file descriptors. This could be avoided 

7977 by blocking signals. 

7978 The dnp2() function is not marked obsolescent because it presents a type-safe version of 

7979 functionality provided in a type-unsafe version by fcntl (). It is used in the POSIX Ada binding. 

7980 The dupl () function is not intended for use in critical regions as a synchronization mechanism. 

7981 In the description of [EBADF], the case oi fildes being out of range is covered by the given case of 

7982 fildes not being valid. The descriptions for fildes and fildes! are different because the only kind of 

7983 invalidity that is relevant tor fildes2 is whether it is out of range; that is, it does not matter 

7984 whether fildes! refers to an open file when the dupl () call is made. 

7985 FUTURE DIRECTIONS 

7986 None. 

7987 SEE ALSO 

7988 close (), fcntl (), open(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

7989 <unistd.h> 
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7990 CHANGE HISTORY 

7991 First released in Issue 1. 

7992 Derived from Issue 1 of the SVID. 

7993 Issue 4 

7994 The <unistd.h> header is added to the SYNOPSIS section. 

7995 [EINTR] is no longer required for dnp() becaus efcntl() does not return [EINTR] for F_DUPFD. 

7996 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

7997 • In the DESCRIPTION, the fourth bullet item describing differences between dup () and 

7998 dup2 () is added. 

7999 • In the ERRORS section, error values returned by dnp() and dnp2() are now described 

8000 separately. 

8001 Issue 6 

8002 The RATIONALE section is added. 
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8003 NAME 

8004 ecvt, fcvt, gcvt — convert a floating-point number to a string (LEGACY) 

8005 SYNOPSIS 

8006 xsi #include <stdlib.h> 


8007 

char 

*ecvt(double 

value, 

int 

ndigit, 

int *decpt, 

int *sign); 

8008 

char 

*fcvt(double 

value, 

int 

ndigit, 

int *decpt, 

int *sign) ; 

8009 

char 

*gcvt(double 

value, 

int 

ndigit, 

char *buf) ; 



8010 

8011 DESCRIPTION 

8012 The ecvt (), fcvt (), and gcvt() functions shall convert floating-point numbers to null-terminated 

8013 strings. 

8014 The ecvt( ) function shall convert value to a null-terminated string of ndigit digits (where ndigit is 

8015 reduced to an unspecified limit determined by the precision of a double) and return a pointer to 

8016 the string. The high-order digit is non-zero, unless the value is 0. The low-order digit is rounded. 

8017 The position of the radix character relative to the beginning of the string is stored in the integer 

8018 pointed to by decpt (negative means to the left of the returned digits). If value is zero, it is 

8019 unspecified whether the integer pointed to by decpt would be 0 or 1. The radix character is not 

8020 included in the returned string. If the sign of the result is negative, the integer pointed to by sign 

8021 is non-zero; otherwise, it is 0. 

8022 If the converted value is out of range or is not representable, the contents of the returned string 

8023 are unspecified. 

8024 The fcvt () function is identical to ecvt () except that ndigit specifies the number of digits desired 

8025 after the radix character. The total number of digits in the result string is restricted to an 

8026 unspecified limit as determined by the precision of a double. 

8027 The gcvt() function shall convert value to a null-terminated string (similar to that of the %g 

8028 format of printf{ )) in the array pointed to by buf and return buf. It produces ndigit significant 

8029 digits (limited to an unspecified value determined by the precision of a double) in %/if possible, 

8030 or %e (scientific notation) otherwise. A minus sign is included in the returned string if value is 

8031 less than 0. A radix character is included in the returned string if value is not a whole number. 

8032 Trailing zeros are suppressed where value is not a whole number. The radix character is 

8033 determined by the current locale. If setlocale( ) has not been called successfully, the default locale, 

8034 POSIX, is used. The default locale specifies a period (' .') as the radix character. The 

8035 LC_NUMERIC category determines the value of the radix character within the current locale. 

8036 These functions need not be reentrant. A function that is not required to be reentrant is not 

8037 required to be thread-safe. 

8038 RETURN VALUE 

8039 The ecvt () and fcvt () functions shall return a pointer to a null-terminated string of digits. 

8040 The gcvt( ) function shall return buf. 

8041 The return values from ecvt( ) and fcvt () may point to static data which may be overwritten by 

8042 subsequent calls to these functions. 

8043 ERRORS 

8044 No errors are defined. 
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8045 EXAMPLES 

8046 None. 

8047 APPLICATION USAGE 

8048 sprintfi ) is preferred over this function. 

8049 RATIONALE 

8050 None. 


8051 FUTURE DIRECTIONS 

8052 These functions may be withdrawn in a future version. 

8053 SEE ALSO 

8054 printf (), setlocale(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

8055 CHANGE HISTORY 

8056 First released in Issue 4, Version 2. 

8057 Issue 5 

8058 Moved from X/OPEN UNIX extension to BASE. 


8059 Normative text previously in the APPLICATION USAGE section is moved to the 

8060 DESCRIPTION. 


8061 

8062 

8063 

8064 


A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 

Issue 6 

In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 

This function is marked LEGACY. 
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8065 NAME 

8066 encrypt — encoding function (CRYPT) 

8067 SYNOPSIS 

8068 xsi #include <unistd.h> 

8069 void encrypt (char block[ 64], int edflag) ; 

8070 

8071 DESCRIPTION 

8072 The encrypt () function provides (rather primitive) access to an implementation-dependent 

8073 encoding algorithm. The key generated by setkey () is used to encrypt the string block with 

8074 encrypt (). 

8075 The block argument to encrypt () is an array of length 64 bytes containing only the bytes with 

8076 numerical value of 0 and 1. The array is modified in place to a similar array using the key set by 

8077 setkey (). If edflag is 0, the argument is encoded. If edflag is 1, the argument may be decoded (see 

8078 the APPLICATION USAGE section); if the argument is not decoded, errno shall be set to 

8079 [ENOSYS]. 

8080 The encrypt () function shall not change the setting of errno if successful. An application wishing 

8081 to check for error situations should set errno to 0 before calling encrypt (). If errno is non-zero on 

8082 return, an error has occurred. 

8083 The encrypt () function need not be reentrant. A function that is not required to be reentrant is 

8084 not required to be thread-safe. 

8085 RETURN VALUE 

8086 The encrypt () function shall return no value. 

8087 ERRORS 

8088 The encrypt () function shall fail if: 

8089 [ENOSYS] The functionality is not supported on this implementation. 

8090 EXAMPLES 

8091 None. 

8092 APPLICATION USAGE 

8093 In some environments, decoding might not be implemented. This is related to U.S. Government 

8094 restrictions on encryption and decryption routines: the DES decryption algorithm cannot be 

8095 exported outside the U.S. Historical practice has been to ship a different version of the 

8096 encryption library without the decryption feature in the routines supplied. Thus the exported 

8097 version of encrypt () does encoding but not decoding. 

8098 RATIONALE 

8099 None. 

8100 FUTURE DIRECTIONS 

8101 None. 

8102 SEE ALSO 

8103 crypt (), setkey (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

8104 CHANGE HISTORY 

8105 First released in Issue 1. 

8106 Derived from Issue 1 of the SVID. 
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8107 Issue 4 

8108 

8109 

8110 
8111 
8112 

8113 

8114 

8115 Issue 5 

8116 

8117 Issue 6 

8118 


The <unistd.h> header is added to the SYNOPSIS section. 

The DESCRIPTION is amended: 

• To specify the encoding algorithm as implementation-dependent 

• To change entry to function 

• To make decoding optional 

The APPLICATION USAGE section is expanded to explain the restrictions on the availability of 
the DES decryption algorithm. 

A note indicating that this function need not be reentrant is added to the DESCRIPTION. 

In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 
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8119 NAME 

8120 endgrent, getgrent, setgrent — group database entry functions 

8121 SYNOPSIS 

8122 xsi #include <grp.h> 

8123 

8124 

8125 

8126 

8127 DESCRIPTION 

8128 The getgrent () function shall return a pointer to a structure containing the broken-out fields of an 

8129 entry in the group database. When first called, getgrent() shall return a pointer to a group 

8130 structure containing the first entry in the group database. Thereafter, it shall return a pointer to a 

8131 group structure containing the next group structure in the group database, so successive calls 

8132 may be used to search the entire database. 

8133 The setgrent () function effectively rewinds the group database to allow repeated searches. 

8134 The endgrent( ) function may be called to close the group database when processing is complete. 

8135 These functions need not be reentrant. A function that is not required to be reentrant is not 

8136 required to be thread-safe. 

8137 RETURN VALUE 

8138 When first called, getgrent() shall return a pointer to the first group structure in the group 

8139 database. Upon subsequent calls it shall return the next group structure in the group database. 

8140 The getgrent( ) function shall return a null pointer on end-of-file or an error and errno may be set 

8141 to indicate the error. 

8142 The return value may point to a static area which is overwritten by a subsequent call to 

8143 getgrgid(), getgrnam(), or getgrent (). 

8144 ERRORS 

8145 The getgrent () function may fail if: 

8146 [EINTR] A signal was caught during the operation. 

8147 [EIO] An I/O error has occurred. 

8148 [EMFILE] |OPEN_MAX} file descriptors are currently open in the calling process. 

8149 [ENFILE] The maximum allowable number of files is currently open in the system. 

8150 EXAMPLES 

8151 None. 

8152 APPLICATION USAGE 

8153 These functions are provided due to their historical usage. Applications should avoid 

8154 dependencies on fields in the group database, whether the database is a single file, or where in 

8155 the file system name space the database resides. Applications should use getgrnam() and 

8156 getgrgid () whenever possible because it avoids these dependencies. 

8157 RATIONALE 

8158 None. 


void endgrent(void) ; 

struct group *getgrent(void) ; 

void setgrent(void); 
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8159 FUTURE DIRECTIONS 

8160 None. 

8161 SEE ALSO 

8162 getgrgid (), getgrnam(), getlogin(), getpwent(), the System Interface Definitions volume of 

8163 IEEE Std. 1003.1-200x, <grp.h> 

8164 CHANGE HISTORY 

8165 First released in Issue 4, Version 2. 

8166 Issue 5 

8167 Moved from X/OPEN UNIX extension to BASE. 

8168 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 

8169 VALUE section. 

8170 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 

8171 Issue 6 

8172 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 
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8173 NAME 

8174 endhostent, freehostent, gethostent, sethostent — network host database functions 

8175 SYNOPSIS 

8176 tinclude <netdb.h> 

8177 void endhostent (void) ; 

8178 void freehostent (struct hostent *ptr) ; 

8179 struct hostent *gethostent (void) ; 

8180 void sethostent (int stayopen) ; 

8181 DESCRIPTION 

8182 These functions enable applications to retrieve information about hosts. This information is 

8183 considered to be stored in a database that can be accessed sequentially or randomly. 

8184 Implementation of this database is unspecified. 

8185 Note: In many cases it is implemented by the Domain Name System, as documented in 

8186 RFC 1034, RFC 1035, and RFC 1886. 

8187 Entries are returned in hostent structures. Refer to gethostbyaddr( ) for a definition of the hostent 

8188 structure. 

8189 The endhostent() function shall close the connection to the database, releasing any open file 

8190 descriptor. 

8191 The freehostent ( ) function shall free the memory occupied by the hostent structure pointed to by 

8192 hostent and any structures pointed to from that structure, provided that hostent was obtained 

8193 by a call to getipnodebyaddr() or getipnodebyname (). Applications shall not call freehostent () 

8194 except to pass it a pointer that was obtained from getipnodebyaddr( ) or getipnodebyname (). 

8195 The gethostent( ) function shall read the next entry in the database, opening a connection to the 

8196 database if necessary. 

8197 The sethostent() function shall open a connection to the database and set the next entry for 

8198 retrieval to the first entry in the database. If the stayopen argument is non-zero, the connection 

8199 shall not be closed by a call to gethostent( ), getipnodebyname (), gethostbyname( ), getipnodebyaddr( ), 

8200 or gethostbyaddr( ), and the implementation may maintain an open file descriptor. 

8201 RETURN VALUE 

8202 Upon successful completion, the getliostent() function shall return a pointer to a hostent 

8203 structure if the requested entry was found, and a null pointer if the end of the database was 

8204 reached or the requested entry was not found. 

8205 ERRORS 

8206 No errors are defined for endhostent (), gethostent ( ), and sethostent (). 

8207 EXAMPLES 

8208 None. 

8209 APPLICATION USAGE 

8210 The hostent structure returned by getipnodebyaddr( ) and getipnodebyname (), and any structures 

8211 pointed to from those structures, are dynamically allocated. Applications should call 

8212 freehostent ( ) to free the memory used by these structures. 

8213 The gethostent() function may return pointers to static data, which may be overwritten by 

8214 subsequent calls to any of these functions. Applications shall not call freehostent ( ) for this area. 
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8215 

RATIONALE 

1 

8216 

None. 

1 

8217 

FUTURE DIRECTIONS 

1 

8218 

None. 

1 

8219 

SEE ALSO 

1 

8220 

8221 

endseruent (), gethostbyaddr(), get host byname (), getipnodebyaddr(), getipnodebyname(), the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, <netdb.h> 

1 

1 

8222 

CHANGE HISTORY 

1 

8223 

First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 

1 
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8224 NAME 

8225 endnetent, getnetbyaddr, getnetbyname, getnetent, setnetent — network database functions 

8226 SYNOPSIS 

8227 #include <netdb.h> 

8228 void endnetent (void) ; 

8229 struct netent *getnetbyaddr(uint32_t net, int type); 

8230 struct netent *getnetbyname (const char * name) ; 

8231 struct netent *getnetent (void) ; 

8232 void setnetent (int stayopen) ; 

8233 DESCRIPTION 

8234 These functions enable applications to retrieve information about networks. This information is 

8235 considered to be stored in a database that can be accessed sequentially or randomly. 

8236 Implementation of this database is unspecified. 

8237 The endnetent( ) function shall close the database, releasing any open file descriptor. 

8238 The getnetbyaddr () function shall search the database from the beginning, and find the first entry 

8239 for which the address family specified by type matches the n_addrtype member and the network 

8240 number net matches the n_net member, opening a connection to the database if necessary. The 

8241 net argument shall be the network number in host byte order. 

8242 The getnetbyname( ) function shall search the database from the beginning and find the first entry 

8243 for which the network name specified by name matches the n_name member, opening a 

8244 connection to the database if necessary. 

8245 The getnetent() function shall read the next entry of the database, opening a connection to the 

8246 database if necessary. 

8247 The setnetent( ) function shall open and rewind the database. If the stayopen argument is non- 

8248 zero, the connection to the net database shall not be closed after each call to getnetent() (either 

8249 directly, or indirectly through one of the other getnet*( ) functions), and the implementation may 

8250 maintain an open file descriptor to the database. 

8251 The getnetbyaddr (), getnetbyname(), and getnetent(), functions shall each return a pointer to a 

8252 netent structure, the members of which shall contain the fields of an entry in the network 

8253 database. 

8254 RETURN VALUE 

8255 Upon successful completion, getnetbyaddr (), getnetbyname(), and getnetent(), shall return a 

8256 pointer to a netent structure if the requested entry was found, and a null pointer if the end of the 

8257 database was reached or the requested entry was not found. Otherwise, a null pointer shall be 

8258 returned. 

8259 ERRORS 

8260 No errors are defined. 
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8261 EXAMPLES 

8262 None. 

8263 APPLICATION USAGE 

8264 The getnetbynddr( ), getnet byname ( ), and getnetent (), functions may return pointers to static data, 

8265 which may be overwritten by subsequent calls to any of these functions. 

8266 RATIONALE 

8267 None. 

8268 FUTURE DIRECTIONS 

8269 None. 

8270 SEE ALSO 

8271 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <netdb.h> 

8272 CHANGE HISTORY 

8273 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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8274 NAME 

8275 endprotoent, getprotobyname, getprotobynumber, getprotoent, setprotoent — network protocol 

8276 database functions 

8277 SYNOPSIS 

8278 #include <netdb.h> 

8279 void endprotoent (void) ; 

8280 struct protoent *getprotobyname(const char * name) ; 

8281 struct protoent *getprotobynumber (int proto); 

8282 struct protoent *getprotoent (void) ; 

8283 void setprotoent (int stayopen) ; 

8284 DESCRIPTION 

8285 These functions enable applications to retrieve information about protocols. This information is 

8286 considered to be stored in a database that can be accessed sequentially or randomly. 

8287 Implementation of this database is unspecified. 

8288 The endprotoent () function shall close the connection to the database, releasing any open file 

8289 descriptor. 

8290 The getprotobyname () function shall search the database from the beginning and find the first 

8291 entry for which the protocol name specified by name matches the p_name member, opening a 

8292 connection to the database if necessary. 

8293 The getprotobynumber () function shall search the database from the beginning and find the first 

8294 entry for which the protocol number specified by number matches the pjproto member, opening a 

8295 connection to the database if necessary. 

8296 The getprotoent () function shall read the next entry of the database, opening a connection to the 

8297 database if necessary. 

8298 The setprotoent () function shall open a connection to the database, and set the next entry to the 

8299 first entry. If the stayopen argument is non-zero, the connection to the network protocol database 

8300 shall not be closed after each call to getprotoent () (either directly, or indirectly through one of the 

8301 other getproto*( ) functions), and the implementation may maintain an open file descriptor for 

8302 the database. 

8303 The getprotobyname (), getprotobynumber (), and getprotoent (), functions shall each return a pointer 

8304 to a protoent structure, the members of which shall contain the fields of an entry in the network 

8305 protocol database. 

8306 RETURN VALUE 

8307 Upon successful completion, getprotobyname (), getprotobynumber (), and getprotoent () return a 

8308 pointer to a protoent structure if the requested entry was found, and a null pointer if the end of 

8309 the database was reached or the requested entry was not found. Otherwise, a null pointer is 

8310 returned. 

8311 ERRORS 

8312 No errors are defined. 
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8313 EXAMPLES 

8314 None. 

8315 APPLICATION USAGE 

8316 The getprotobyname(), getprotobynnmber(), and getprotoent () functions may return pointers to 

8317 static data, which may be overwritten by subsequent calls to any of these functions. 

8318 RATIONALE 

8319 None. 

8320 FUTURE DIRECTIONS 

8321 None. 

8322 SEE ALSO 

8323 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <netdb.h> 

8324 CHANGE HISTORY 

8325 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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8326 NAME 

8327 endpwent, getpwent, setpwent — user database functions 

8328 SYNOPSIS 

8329 xsi #include <pwd.h> 

8330 

8331 

8332 

8333 

8334 DESCRIPTION 

8335 The getpivent( ) function shall return a pointer to a structure containing the broken-out fields of 

8336 an entry in the user database. Each entry in the user database contains a passwd structure. When 

8337 first called, getpivent( ) shall return a pointer to a passwd structure containing the first entry in 

8338 the user database. Thereafter, it shall return a pointer to a passwd structure containing the next 

8339 entry in the user database. Successive calls can be used to search the entire user database. 

8340 If an end-of-file or an error is encountered on reading, getpwent () shall return a null pointer. 

8341 The setpzvent( ) function effectively rewinds the user database to allow repeated searches. 

8342 The endpzvent( ) function may be called to close the user database when processing is complete. 

8343 These functions need not be reentrant. A function that is not required to be reentrant is not 

8344 required to be thread-safe. 

8345 RETURN VALUE 

8346 The getpwent () function shall return a null pointer on end-of-file or error. 

8347 ERRORS 

8348 The getpivent( ), setpwent( ), and endpivent( ) functions may fail if: 

8349 [EIO] An 1/O error has occurred. 

8350 In addition, getpwent () and setpwent () may fail if: 

8351 [EMFILE] |OPEN_MAX[ file descriptors are currently open in the calling process. 

8352 [ENFILE] The maximum allowable number of files is currently open in the system. 

8353 The return value may point to a static area which is overwritten by a subsequent call to 

8354 getpiv:ud( ), getpwnam( ), or getpwent (). 

8355 EXAMPLES 

8356 Searching the User Database 

8357 The following example uses the getpwent () function to get successive entries in the user 

8358 database, returning a pointer to a passwd structure that contains information about each user. 

8359 The call to endpwent() closes the user database and cleans up. 

8360 #include <pwd.h> 

8361 

8362 struct passwd *p; 

8363 

8364 while ( (p = getpwent ()) != NULL) { 

8365 

8366 } 


void endpwent(void) ; 

struct passwd *getpwent(void) ; 

void setpwent(void); 
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8367 endpwent () ; 

8368 

8369 APPLICATION USAGE 

8370 These functions are provided due to their historical usage. Applications should avoid 

8371 dependencies on fields in the password database, whether the database is a single file, or where 

8372 in the file system name space the database resides. Applications should use getpivnid() 

8373 whenever possible because it avoids these dependencies. 

8374 RATIONALE 

8375 None. 

8376 FUTURE DIRECTIONS 

8377 None. 

8378 SEE ALSO 

8379 endgrent(), getlogin(), getpzvnam(), getpivirid(), the System Interface Definitions volume of 

8380 IEEE Std. 1003.1-200x, <pwd.h> 

8381 CHANGE HISTORY 

8382 First released in Issue 4, Version 2. 

8383 Issue 5 

8384 Moved from X/OPEN UNIX extension to BASE. 

8385 Normative text previously in the APPLICATION USAGE section is moved to the RETURN 

8386 VALUE section. 

8387 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 

8388 Issue 6 

8389 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 
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8390 NAME 

8391 endservent, getservbyname, getservbyport, getservent, setservent — network services database 

8392 functions 

8393 SYNOPSIS 

8394 #include <netdb.h> 

8395 void endservent (void) ; 

8396 struct servent *getservbyname(const char *name, const char *proto) ; 

8397 struct servent *getservbyport(int port, const char *proto ); 

8398 struct servent *getservent (void) ; 

8399 void setservent (int stayopen) ; 

8400 DESCRIPTION 

8401 These functions enable applications to retrieve information about network services. This 

8402 information is considered to be stored in a database that can be accessed sequentially or 

8403 randomly. Implementation of this database is unspecified. 

8404 The endservent( ) function shall close the database, releasing any open file descriptor. 

8405 The getservbyname () function shall search the database from the beginning and find the first 

8406 entry for which the service name specified by name matches the s_name member and the protocol 

8407 name specified by proto matches the sjproto member, opening a connection to the database if 

8408 necessary. If proto is a null pointer, any value of the s_proto member shall be matched. 

8409 The getservbyport () function shall search the database from the beginning and find the first entry 

8410 for which the port specified by port matches the sjport member and the protocol name specified 

8411 by proto matches the sjproto member, opening a connection to the database if necessary. If proto 

8412 is a null pointer, any value of the sjproto member shall be matched. The port argument shall be in 

8413 network byte order. 

8414 The getservent () function shall read the next entry of the database, opening a connection to the 

8415 database if necessary. 

8416 The setservent () function shall open a connection to the database, and set the next entry to the 

8417 first entry. If the stayopen argument is non-zero, the net database shall not be closed after each 

8418 call to the getservent () function (either directly, or indirectly through one of the other getserv*( ) 

8419 functions), and the implementation may maintain an open file descriptor for the database. 

8420 The getservbyname (), getservbyport (), and getservent() functions shall each return a pointer to a 

8421 servent structure, the members of which shall contain the fields of an entry in the network 

8422 services database. 

8423 RETURN VALUE 

8424 Upon successful completion, getservbyname (), getservbyport (), and getservent() return a pointer to 

8425 a servent structure if the requested entry was found, and a null pointer if the end of the database 

8426 was reached or the requested entry was not found. Otherwise, a null pointer is returned. 

8427 ERRORS 

8428 No errors are defined. 
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8429 EXAMPLES 

8430 None. 

8431 APPLICATION USAGE 

8432 The port argument of getservbyport ( ) need not be compatible with the port values of all address 

8433 families. 

8434 The getservbyname (), getservbyport (), and getservent() functions may return pointers to static 

8435 data, which may be overwritten by subsequent calls to any of these functions. 

8436 RATIONALE 

8437 None. 

8438 FUTURE DIRECTIONS 

8439 None. 

8440 SEE ALSO 

8441 endhostent(), endprotoent(), htonl(), inet_addr(), the System Interface Definitions volume of 

8442 IEEE Std. 1003.1-200x, <netdb.h> 

8443 CHANGE HISTORY 

8444 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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8445 NAME 

8446 endutxent, getutxent, getutxid, getutxline, pututxline, setutxent — user accounting database 

8447 functions 

8448 SYNOPSIS 

8449 xsi #include <utmpx.h> 

8450 void endutxent (void) ; 

8451 struct utmpx *getutxent (void) ; 

8452 struct utmpx *getutxid (const struct utmpx *id) ; 

8453 struct utmpx *getutxline (const struct utmpx *line) ; 

8454 struct utmpx *pututxline(const struct utmpx * utmpx ); 

8455 void setutxent (void) ; 

8456 

8457 DESCRIPTION 

8458 These functions provide access to the user accounting database. 

8459 The getntxent() function reads in the next entry from the user accounting database. If the 

8460 database is not already open, it opens it. If it reaches the end of the database, it fails. 

8461 The getutxid() function searches forward from the current point in the database. If the utjype 

8462 value of the utmpx structure pointed to by id is BOOT_TIME, OLD_TIME, or NEW_TIME, then 

8463 it stops when it finds an entry with a matching ut_type value. If the ut_type value is 

8464 INIT_PROCESS, LOGIN_PROCESS, USER_PROCESS, or DEAD_PROCESS, then it stops when 

8465 it finds an entry whose type is one of these four and whose ut_id member matches the ut_id 

8466 member of the utmpx structure pointed to by id. If the end of the database is reached without a 

8467 match, getutxid () fails. 

8468 The getutxid () or getutxline{) function may cache data. For this reason, to use getutxline{) to 

8469 search for multiple occurrences, it is necessary to zero out the static data after each success, or 

8470 getutxline{ ) could just return a pointer to the same utmpx structure over and over again. 

8471 There is one exception to the rule about removing the structure before further reads are done. 

8472 The implicit read done by pututxline( ) (if it finds that it is not already at the correct place in the 

8473 user accounting database) shall not modify the static structure returned by getutxent(), 

8474 getutxid (), or getutxline(), if the application has just modified this structure and passed the 

8475 pointer back to pututxline{ ). 

8476 For all entries that match a request, the ut_type member indicates the type of the entry. Other 

8477 members of the entry shall contain meaningful data based on the value of the ut_type member as 

8478 follows: 


8479 

ut_type Member 

Other Members with Meaningful Data 

8480 

EMPTY 

No others 

8481 

BOOT_TIME 

ut_tv 

8482 

OLD_TIME 

llt_tv 

8483 

NEW_TIME 

llt_tv 

8484 

USER_PROCESS 

ut_id, ut_user (login name of the user), utjine, ut_pid, utjv 

8485 

INIT_PROCESS 

utjd, utjpid, utjv 

8486 

LOGIN_PROCESS 

utjd, ut_user (implementation-dependent name of the 

8487 


login process), ut_pid, utjv 

8488 

DEAD_PROCESS 

utjd, ut_pid, utjv 


8489 The getutxline () function searches forward from the current point in the database until it finds an 

8490 entry of the type LOGIN_PROCESS or USER_PROCESS which also has a utjine value matching 

8491 that in the utmpx structure pointed to by line. If the end of the database is reached without a 
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8492 match, getutxline( ) fails. 

8493 If the process has appropriate privileges, the pututxline( ) function writes out the structure into 

8494 the user accounting database. It uses getntxid() to search for a record that satisfies the request. If 

8495 this search succeeds, then the entry is replaced. Otherwise, a new entry is made at the end of the 

8496 user accounting database. 

8497 The setutxent( ) function resets the input to the beginning of the database. This should be done 

8498 before each search for a new entry if it is desired that the entire database be examined. 

8499 The endntxent( ) function closes the user accounting database. 

8500 These functions need not be reentrant. A function that is not required to be reentrant is not 

8501 required to be thread-safe. 

8502 RETURN VALUE 

8503 Upon successful completion, getntxent(), getntxid(), and getntxline{) shall return a pointer to a 

8504 utmpx structure containing a copy of the requested entry in the user accounting database. 

8505 Otherwise, a null pointer shall be returned. 

8506 The return value may point to a static area which is overwritten by a subsequent call to 

8507 getutxid() or gehitxline (). 

8508 Upon successful completion, pututxline{ ) shall return a pointer to a utmpx structure containing a 

8509 copy of the entry added to the user accounting database. Otherwise, a null pointer shall be 

8510 returned. 

8511 The endntxent( ) and s etutxent( ) functions shall return no value. 

8512 ERRORS 

8513 No errors are defined for the endntxent{), getntxent(), getntxid(), getutxline(), and setutxent() 

8514 functions. 

8515 The pututxlinei ) function may fail if: 

8516 [EPERM] The process does not have appropriate privileges. 

8517 EXAMPLES 

8518 None. 

8519 APPLICATION USAGE 

8520 The sizes of the arrays in the structure can be found using the sizeof operator. 

8521 RATIONALE 

8522 None. 

8523 FUTURE DIRECTIONS 

8524 None. 

8525 SEE ALSO 

8526 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <utmpx.h> 

8527 CHANGE HISTORY 

8528 First released in Issue 4, Version 2. 

8529 Issue 5 

8530 Moved from X/OPEN UNIX extension to BASE. 

8531 Normative text previously in the APPLICATION USAGE section is moved to the 

8532 DESCRIPTION. 


System Interfaces, Issue 6 


269 



endutxent() 


System Interfaces 


8533 A note indicating that these functions need not be reentrant is added to the DESCRIPTION. 

8534 Issue 6 

8535 In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 
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8536 NAME 

8537 environ — array of character pointers to the environment strings 

8538 SYNOPSIS 

8539 extern char **environ; 

8540 DESCRIPTION 

8541 Refer to the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, I 

8542 Environment Variables and exec. I 
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8543 NAME 

8544 erand48 — generate uniformly distributed pseudo-random numbers 

8545 SYNOPSIS 

8546 xsi #include <stdlib.h> 

8547 double erand48(unsigned short int xsubi[3]); 

8548 

8549 DESCRIPTION 

8550 Refer to drand48 (). 
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8551 NAME 

8552 erf, erfc — error and complementary error functions 

8553 SYNOPSIS 

8554 xsi #include <math.h> 

8555 double erf (double x) ; 

8556 double erfc (double x) ; 

8557 

8558 DESCRIPTION 

8559 The erf () function shall compute the error function of x, defined as: 



8561 The erfc( ) function shall compute 1.0 - erf(x). 

8562 An application wishing to check for error situations should set errno to 0 before calling erf( ). If 

8563 errno is non-zero on return, or the return value is NaN, an error has occurred. 

8564 RETURN VALUE 

8565 Upon successful completion, erf() and erfc() shall return the value of the error function and 

8566 complementary error function, respectively. 

8567 If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

8568 If the correct value would cause underflow, 0 shall be returned and errno may be set to 

8569 [ERANGE], 

8570 ERRORS 

8571 The erf( ) and erfc( ) functions may fail if: 

8572 [EDOM] The value of x is NaN. 

8573 [ERANGE] The result underflows 

8574 No other errors shall occur. 

8575 EXAMPLES 

8576 None. 

8577 APPLICATION USAGE 

8578 The erfc( ) function is provided because of the extreme loss of relative accuracy if erf(x) is called 

8579 for large x and the result subtracted from 1.0. 

8580 RATIONALE 

8581 None. 

8582 FUTURE DIRECTIONS 

8583 None. 

8584 SEE ALSO 

8585 isnan (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

8586 CHANGE HISTORY 

8587 First released in Issue 1. 

8588 Derived from Issue 1 of the SVID. 
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8589 Issue 4 

8590 References to matherr () are removed. 

8591 The RETURN VALUE and ERRORS sections are substantially rewritten to rationalize error 

8592 handling in the mathematics functions. 

8593 Issue 5 

8594 The DESCRIPTION is updated to indicate how an application should check for an error. This 

8595 text was previously published in the APPLICATION USAGE section. 
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8596 NAME 

8597 errno — error return value 

8598 Notes to Reviewers 

8599 This section zvith side shading zvill not appear in the final copy. - Ed. 

8600 Further CX markings need to be defined for this page. 

8601 SYNOPSIS 

8602 #include <errno.h> 

8603 DESCRIPTION 

8604 errno is used by many functions to return error values. 

8605 Many functions provide an error number in errno which has type int and is defined in <errno.h>. 

8606 The value of errno shall be defined only after a call to a function for which it is explicitly stated to 

8607 be set and until it is changed by the next function call. The value of errno should only be 

8608 examined when it is indicated to be valid by a function's return value. Programs should obtain 

8609 the definition of errno by the inclusion of <errno.h>. The practice of defining errno in a program 

8610 as extern int errno is obsolescent. No function in this volume of IEEE Std. 1003.1-200x shall set 

8611 errno to 0 to indicate an error. 

8612 It is unspecified whether errno is a macro or an identifier declared with external linkage. If a 

8613 macro definition is suppressed in order to access an actual object, or a program defines an 

8614 identifier with the name errno, the behavior is undefined. 

8615 The symbolic values stored in errno are documented in the ERRORS sections on all relevant 

8616 pages. 

8617 RETURN VALUE 

8618 None. 

8619 ERRORS 

8620 None. 

8621 EXAMPLES 

8622 None. 

8623 APPLICATION USAGE 

8624 Previously both POSIX and X/Open documents were more restrictive than the ISO C standard 

8625 in that they required errno to be defined as an external variable, whereas the ISO C standard 

8626 required only that errno be defined as a modifiable lvalue with type int. 

8627 A program that uses errno for error checking should set it to 0 before a function call, then inspect 

8628 it before a subsequent function call. 

8629 RATIONALE 

8630 None. 

8631 FUTURE DIRECTIONS 

8632 None. 

8633 SEE ALSO 

8634 Section 2.3, the System Interface Definitions volume of IEEE Std. 1003.1-200x, <errno.h> 

8635 CHANGE HISTORY 

8636 First released in Issue 1. 

8637 Derived from Issue 1 of the SVID. 
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8638 issue 4 

8639 The FUTURE DIRECTIONS section is deleted. 

8640 The following changes are incorporated for alignment with the ISO C standard: 

8641 • The DESCRIPTION now guarantees that errno is set to 0 at program start-up, and that it is I 

8642 never reset to 0 by any XSI function. I 

8643 • The APPLICATION USAGE section is added. This issue is aligned with the ISO C standard, 

8644 which permits errno to be a macro. 

8645 Issue 5 

8646 The following sentence is deleted from the DESCRIPTION: "The value of errno is 0 at program I 

8647 start-up, but is never set to 0 by any XSI function". The DESCRIPTION also no longer states that I 

8648 conforming implementations may support the declaration: 

8649 extern int errno; 

8650 Both these historical behaviors are obsolete and may not be supported by some 

8651 implementations. 
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8652 NAME 

8653 environ, execl, execv, execle, execve, execlp, execvp — execute a file 

8654 SYNOPSIS 

8655 #include <unistd.h> 

8656 extern char **environ; 


8657 

int 

execl(const char *path, 

const char * 

argO, . 

. . . /*, (char * 

)0 */); 

8658 

int 

execv(const char *path, 

char *const 

argv[] ) 

r 


8659 

int 

execle(const char *path, 

const char 

*argO, 

... /*, 


8660 


(char *)0, char *const envp[]*/); 




8661 

int 

execve(const char *path, 

char *const 

argv[ ] 

, char *const 

envp [ ] ) ; 

8662 

int 

execlp(const char *file, 

const char 

*argO, 

... /*, (char 

*)0 */); 

8663 

int 

execvp(const char *file, 

char *const 

argv[ ] 

); 



8664 DESCRIPTION 

8665 The exec functions shall replace the current process image with a new process image. The new 

8666 image is constructed from a regular, executable file called the new process image file. There shall 

8667 be no return from a successful exec, because the calling process image is overlaid by the new 

8668 process image. 

8669 When a C-language program is executed as a result of this call, it shall be entered as a C- 

8670 language function call as follows: 

8671 int main ( int argc, char *argv[]) ; 

8672 where argc is the argument count and argv is an array of character pointers to the arguments 

8673 themselves. In addition, the following variable: 

8674 extern char **environ; 

8675 is initialized as a pointer to an array of character pointers to the environment strings. The argv 

8676 and environ arrays are each terminated by a null pointer. The null pointer terminating the argv 

8677 array is not counted in argc. 

8678 thr Conforming multi-threaded applications shall not use the environ variable to access or modify 

8679 any environment variable while any other thread is concurrently modifying any environment 

8680 variable. A call to any function dependent on any environment variable shall be considered a use 

8681 of the environ variable to access that environment variable. 

8682 The arguments specified by a program with one of the exec functions shall be passed on to the 

8683 new process image in the corresponding main ( ) arguments. 

8684 The argument path points to a path name that identifies the new process image file. 

8685 The argument file is used to construct a path name that identifies the new process image file. If 

8686 the file argument contains a slash character, the file argument shall be used as the path name for 

8687 this file. Otherwise, the path prefix for this file is obtained by a search of the directories passed 

8688 as the environment variable PATH (see the System Interface Definitions volume of I 

8689 IEEE Std. 1003.1-200x, Chapter 8, Environment Variables). If this environment variable is not I 

8690 present, the results of the search are implementation-dependent. I 

8691 If the process image file is not a valid executable object, execlp () and execvp () use the contents of 

8692 that file as standard input to a command interpreter conforming to system (). In this case, the 

8693 command interpreter becomes the new process image. 

8694 The arguments represented by argO,. .. are pointers to null-terminated character strings. These 

8695 strings constitute the argument list available to the new process image. The list is terminated by 

8696 a null pointer. The argument argO should point to a file name that is associated with the process 
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8697 being started by one of the exec functions. 

8698 The argument argv is an array of character pointers to null-terminated strings. The application I 

8699 shall ensure that the last member of this array is a null pointer. These strings constitute the I 

8700 argument list available to the new process image. The value in argv[0] should point to a file I 

8701 name that is associated with the process being started by one of the exec functions. 

8702 The argument envp is an array of character pointers to null-terminated strings. These strings 

8703 constitute the environment for the new process image. The envp array is terminated by a null 

8704 pointer. 

8705 For those forms not containing an envp pointer (execl (), execv(), execlp (), and execvp ()), the 

8706 environment for the new process image is taken from the external variable environ in the calling 

8707 process. 

8708 The number of bytes available for the new process' combined argument and environment lists is 

8709 {ARG_MAX}. It is implementation-dependent whether null terminators, pointers, and/or any 

8710 alignment bytes are included in this total. 

8711 File descriptors open in the calling process image remain open in the new process image, except 

8712 for those whose close-on-exec flag FD_CLOEXEC is set. For those file descriptors that remain 

8713 open, all attributes of the open file description remain unchanged. For any file descriptor that is I 

8714 closed for this reason, file locks are removed as a result of the close as described in close ( ). Locks I 

8715 that are not removed by closing of file descriptors remain unchanged. I 

8716 Directory streams open in the calling process image shall be closed in the new process image. 

8717 xsi The state of conversion descriptors and message catalog descriptors in the new process image is 

8718 undefined. For the new process, the equivalent of: 

8719 setlocale (LC_ALL, "C") 

8720 is executed at start-up. I 

8721 Signals set to the default action (SIG_DFL) in the calling process image shall be set to the default 

8722 action in the new process image. Signals set to be ignored (SIG_IGN) by the calling process 

8723 image shall be set to be ignored by the new process image. Signals set to be caught by the calling 

8724 xsi process image shall be set to the default action in the new process image (see <signal.h>). After 

8725 a successful call to any of the exec functions, alternate signal stacks are not preserved and the 

8726 SA_ONSTACK flag shall be cleared for all signals. 

8727 After a successful call to any of the exec functions, any functions previously registered by atexit() 

8728 are no longer registered. 

8729 xsi If the ST_NOSUID bit is set for the file system containing the new process image file, then the 

8730 effective user ID, effective group ID, saved set-user-ID, and saved set-group-ID are unchanged 

8731 in the new process image. Otherwise, if the set-user-ID mode bit of the new process image file is 

8732 set, the effective user ID of the new process image is set to the user ID of the new process image 

8733 file. Similarly, if the set-group-ID mode bit of the new process image file is set, the effective 

8734 group ID of the new process image is set to the group ID of the new process image file. The real 

8735 user ID, real group ID, and supplementary group IDs of the new process image remain the same 

8736 as those of the calling process image. The effective user ID and effective group ID of the new 

8737 process image shall be saved (as the saved set-user-ID and the saved set-group-ID) for use by 

8738 setnid(). 

8739 xsi Any shared memory segments attached to the calling process image shall not be attached to the 

8740 new process image. 
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8741 sem Any named semaphores open in the calling process shall be closed as if by appropriate calls to 

8742 sem_close(). 

8743 tym Any blocks of typed memory that were mapped in the calling process are unmapped, as if I 

8744 mnnmap( ) was implicitly called to unmap them. I 

8745 ml Memory locks established by the calling process via calls to mlockall () or mlock() shall be I 

8746 removed. If locked pages in the address space of the calling process are also mapped into the 

8747 address spaces of other processes and are locked by those processes, the locks established by the 

8748 other processes shall be unaffected by the call by this process to the exec function. If the exec 

8749 function fails, the effect on memory locks is unspecified. 

8750 mf i shm Memory mappings created in the process are unmapped before the address space is rebuilt for 

8751 the new process image. 

8752 ps For the SCFIED_FIFO and SCHED_RR scheduling policies, the policy and priority settings shall 

8753 not be changed by a call to an exec function. For other scheduling policies, the policy and priority 

8754 settings on exec are implementation-dependent. 

8755 tmr Per-process timers created by the calling process shall be deleted before replacing the current 

8756 process image with the new process image. 

8757 msg All open message queue descriptors in the calling process shall be closed, as described in 

8758 mq_close(). 

8759 aio Any outstanding asynchronous I/O operations may be canceled. Those asynchronous I/O 

8760 operations that are not canceled shall complete as if the exec function had not yet occurred, but 

8761 any associated signal notifications shall be suppressed. It is unspecified whether the exec 

8762 function itself blocks awaiting such I/O completion. In no event, however, shall the new process 

8763 image created by the exec function be affected by the presence of outstanding asynchronous I/O 

8764 operations at the time the exec function is called. Whether any I/O is canceled, and which I/O 

8765 may be canceled upon exec, is implementation-dependent. 

8766 cpt The new process image shall inherit the CPU-time clock of the calling process image. This means I 

8767 that the process CPU-time clock of the process being exceed shall not be reinitialized or altered I 

8768 as a result of the exec function other than to reflect the time spent by the process executing the I 

8769 exec function itself. I 

8770 tct The initial value of the CPU-time clock of the initial thread of the new process image shall be set I 

8771 to zero. I 

8772 The new process also inherits at least the following attributes from the calling process image: I 

8773 xsi • Nice value (see nice( )) 

8774 xsi • semadj values (see semop( )) 

8775 • Process ID 

8776 • Parent process ID 

8777 • Process group ID 

8778 • Session membership 

8779 • Real user ID 

8780 • Real group ID 

8781 • Supplementary group IDs 
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8782 • Time left until an alarm clock signal (see alarm ()) 

8783 • Current working directory 

8784 • Root directory 

8785 • File mode creation mask (see nmask ()) 

8786 xsi • File size limit (see ulimit ()) 

8787 • Process signal mask (see sigprocmask()) 

8788 • Pending signal (see sigpendingO) 

8789 • tms_utime, tms_stime, tms_cutime, and tms_cstime (see times( )) 

8790 xsi • Resource limits 

8791 xsi • Controlling terminal 

8792 xsi • Interval timers 

8793 All other process attributes defined in this volume of IEEE Std. 1003.1-200x shall be the same in 

8794 the new and old process images. The inheritance of process attributes not defined by this 

8795 volume of IEEE Std. 1003.1-200x is implementation-dependent. 

8796 A call to any exec function from a process with more than one thread results in all threads being 

8797 terminated and the new executable image being loaded and executed. No destructor functions 

8798 shall be called. 


8799 Upon successful completion, the exec functions shall mark for update the st_atime field of the file. 

8800 If an exec function failed but was able to locate the process image file, whether the st_atime field is 

8801 marked for update is unspecified. Should the exec function succeed, the process image file shall 

8802 be considered to have been opened with open(). The corresponding close () shall be considered 

8803 to occur at a time after this open, but before process termination or successful completion of a 

8804 subsequent call to one of the exec functions. The argv[] and envp [ J arrays of pointers and the 

8805 strings to which those arrays point shall not be modified by a call to one of the exec functions, 

8806 except as a consequence of replacing the process image. 

8807 xsi The saved resource limits in the new process image are set to be a copy of the process' 

8808 corresponding hard and soft limits. 

8809 RETURN VALUE 

8810 If one of the exec functions returns to the calling process image, an error has occurred; the return 

8811 value shall be -1, and errno shall be set to indicate the error. 


8812 ERRORS 

8813 The exec functions shall fail if: 


8814 

8815 

8816 


[E2BIG] The number of bytes used by the new process image's argument list and 

environment list is greater than the system-imposed limit of {ARG_MAX} 
bytes. 


8817 

8818 

8819 

8820 

8821 

8822 

8823 


[EACCES] Search permission is denied for a directory listed in the new process image 

file's path prefix, or the new process image file denies execution permission, 
or the new process image file is not a regular file and the implementation does 
not support execution of files of its type. I 

[EINVAL] The new process image file has the appropriate permission and has a I 

recognized executable binary format, but the system does not support I 
execution of a file with this format. I 
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8824 [ELOOP] A loop exists in symbolic links encountered during resolution of the path or file I 

8825 argument. I 


8826 

8827 

8828 

8829 

8830 


[ENAMETOOLONG] 

The length of the path or file arguments, or an element of the environment 
variable PATH prefixed to a file, exceeds {PATH_MAX}, or a path name 
component is longer than {NAME_MAX} while _POSIX_NO_TRUNC is in 
effect. 


8831 

8832 

8833 

8834 


[ENOENT] A component of path or file does not name an existing file or path or file is an 

empty string. 

[ENOTDIR] A component of the new process image file's path prefix is not a directory. 

The exec functions, except for execlp () and execvp (), shall fail if: 


8835 

8836 

8837 

8838 

8839 

8840 

8841 

8842 

8843 

8844 


[ENOEXEC] The new process image file has the appropriate access permission but has an 
unrecognized format. 

The exec functions may fail if: 

[ELOOP] More than ]SYMLOOP_MAX} symbolic links were encountered during 

resolution of the path or file argument. 

[ENAMETOOLONG] 

As a result of encountering a symbolic link in resolution of the path argument, 
the length of the substituted path name string exceeded ]PATH_MAX[. 

[ENOMEM] The new process image requires more memory than is allowed by the 
hardware or system-imposed memory management constraints. 


8845 [ETXTBSY] 

8846 

8847 EXAMPLES 

8848 Using execl() 

8849 The following example executes the Is command, specifying the path name of the executable 

8850 (/bin/ls) and using arguments supplied directly to the command to produce single-column 

8851 output. 

8852 #include <unistd.h> 

8853 int ret; 

8854 

8855 ret = execl ("/bin/ls", "Is", 1", NULL); 


The new process image file is a pure procedure (shared text) file that is 
currently open for writing by some process. 


8856 Using execle() 

8857 The following example is similar to Using execl(). In addition, it specifies the environment for 

8858 the new process image using the env argument. 

8859 #include <unistd.h> 

8860 int ret; 

8861 char *env[] = { "HOME=/usr/home", "LOGNAME=home", NULL }; 

8862 

8863 ret = execle ("/bin/ls", "Is", "-1", NULL, env); 
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8864 Using execlp( ) 

8865 The following example searches for the location of the Is command among the directories 

8866 specified by the PATH environment variable. 

8867 #include <unistd.h> 

8868 int ret; 

8869 

8870 ret = execlp ("Is", "Is", "-1", NULL); 

8871 Using execvf) 

8872 The following example passes arguments to the Is command in the cmd array. 

8873 #include <unistd.h> 

8874 int ret; 

8875 char *cmd[] = { "Is", "-1", NULL }; 

8876 

8877 ret = execv ("/bin/ls", cmd); 

8878 Using execvet) 

8879 The following example passes arguments to the Is command in the and array, and specifies the 

8880 environment for the new process image using the env argument. 

8881 #include <unistd.h> 

8882 int ret; 

8883 char *cmd[] = { "Is", "-1", NULL }; 

8884 char *env[] = { "HOME=/usr/home", "LOGNAME=home", NULL }; 

8885 

8886 ret = execve ("/bin/ls", cmd, env); 

8887 Using execvpt ) 

8888 The following example searches for the location of the Is command among the directories 

8889 specified by the PATH environment variable, and passes arguments to the Is command in the 

8890 cmd array. 

8891 #include <unistd.h> 

8892 int ret; 

8893 char *cmd[] = { "Is", "-1", NULL }; 

8894 

8895 ret = execvp ("Is", cmd); 

8896 APPLICATION USAGE 

8897 As the state of conversion descriptors and message catalog descriptors in the new process image 

8898 is undefined, portable applications should not rely on their use and should close them prior to 

8899 calling one of the exec functions. 

8900 Applications that require other than the default POSIX locale should call s etlocale() with the 

8901 appropriate parameters to establish the locale of the new process. 

8902 The environ array should not be accessed directly by the application. 
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8903 RATIONALE 

8904 Early proposals required that the value of argc passed to main() be "one or greater". This was 

8905 driven by the same requirement in drafts of the ISO C standard. In fact, historical 

8906 implementations have passed a value of zero when no arguments are supplied to the caller of 

8907 the exec functions. This requirement was removed from the ISO C standard and subsequently 

8908 removed from this volume of IEEE Std. 1003.1-200x as well. The wording, in particular the use of 

8909 the word should, requires a Strictly Conforming POSIX Application to pass at least one argument 

8910 to the exec function, thus guaranteeing that argc be one or greater when invoked by such an 

8911 application. In fact, this is good practice, since many existing applications reference argv[ 0] 

8912 without first checking the value of argc. 

8913 The requirement on a Strictly Conforming POSIX Application also states that the value passed 

8914 as the first argument be a file name associated with the process being started. Although some 

8915 existing applications pass a path name rather than a file name in some circumstances, a file 

8916 name is more generally useful, since the common usage of argv[ 0] is in printing diagnostics. In 

8917 some cases the file name passed is not the actual file name of the file; for example, many 

8918 implementations of the login utility use a convention of prefixing a hyphen ') to the actual 

8919 file name, which indicates to the command interpreter being invoked that it is a "login shell". I 

8920 The intent is to make it clear that although the call to exec family functions itself will not have I 

8921 any effect on the file locks, an exec function may subsequently call the close () function which I 

8922 may have an effect on file locks. It was also noted that file locks are not an attribute of the open I 

8923 file descriptor. I 

8924 Some systems can exec shell scripts. I 

8925 One common historical implementation is that the execl(), execv(), execle(), and execve() 

8926 functions return an [ENOEXEC] error for any file not recognizable as executable, including a 

8927 shell script. When the execlp( ) and execvp( ) functions encounter such a file, they assume the file 

8928 to be a shell script and invoke a known command interpreter to interpret such files. These 

8929 implementations of execvp () and execlp() only give the [ENOEXEC] error in the rare case of a 

8930 problem with the command interpreter's executable file. Because of these implementations, the 

8931 [ENOEXEC] error is not mentioned for execlp( ) or execvp (), although implementations can still 

8932 give it. 

8933 Another way that some historical implementations handle shell scripts is by recognizing the first 

8934 two bytes of the file as the character string " # ! " and using the remainder of the first line of the 

8935 file as the name of the command interpreter to execute. 

8936 Some implementations provide a third argument to main() called envp. This is defined as a 

8937 pointer to the environment. The ISO C standard specifies invoking main () with two arguments, 

8938 so implementations must support applications written this way. Since this volume of 

8939 IEEE Std. 1003.1-200x defines the global variable environ, which is also provided by historical 

8940 implementations and can be used anywhere that envp could be used, there is no functional need 

8941 for the envp argument. Applications should use the getenv () function rather than accessing the 

8942 environment directly via either envp or environ. Implementations are required to support the 

8943 two-argument calling sequence, but this does not prohibit an implementation from supporting 

8944 envp as an optional third argument. 

8945 This volume of IEEE Std. 1003.1-200x specifies that signals set to SIG_IGN remain set to 

8946 SIG_IGN, and that the process signal mask be unchanged across an exec. This is consistent with 

8947 historical implementations, and it permits some useful functionality, such as the nohnp 

8948 command. However, it should be noted that many existing applications wrongly assume that 

8949 they start with certain signals set to the default action and/or unblocked. In particular, 

8950 applications written with a simpler signal model that does not include blocking of signals, such 

8951 as the one in the ISO C standard, may not behave properly if invoked with some signals blocked. 
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8952 Therefore, it is best not to block or ignore signals across execs without explicit reason to do so, 

8953 and especially not to block signals across execs of arbitrary (not closely co-operating) programs. 

8954 The exec functions always save the value of the effective user ID and effective group ID of the I 

8955 process at the completion of the exec, whether or not the set-user-ID or the set-group-ID bit of 

8956 the process image file is set. 

8957 The statement about argv[] and envp [] being constants is included to make explicit to future 

8958 writers of language bindings that these objects are completely constant. Due to a limitation of 

8959 the ISO C standard, it is not possible to state that idea in standard C. Specifying two levels of 

8960 const-qualification for the argv[ ] and envp[ ] parameters for the exec functions may seem to be the 

8961 natural choice, given that these functions do not modify either the array of pointers or the 

8962 characters to which the function points, but this would disallow existing correct code. Instead, 

8963 only the array of pointers is noted as constant. The table of assignment compatibility for dst=src, 

8964 derived from the ISO C standard summarizes the compatibility: 


8965 

dst: 

char*]] 

const char*[ ] 

char *const[ ] 

const char *const[ ] 

8966 

src: 





8967 

char *[ ] 

VALID 

— 

VALID 

— 

8968 

const char *[ ] 

— 

VALID 

— 

VALID 

8969 

char * const [ ] 

— 

— 

VALID 

— 

8970 

const char *const[ ] 

— 

— 

— 

VALID 


8971 Since all existing code has a source type matching the first row, the column that gives the most 

8972 valid combinations is the third column. The only other possibility is the fourth column, but 

8973 using it would require a cast on the argv or envp arguments. It is unfortunate that the fourth 

8974 column cannot be used, because the declaration a non-expert would naturally use would be that 

8975 in the second row. 


8976 The ISO C standard and this volume of IEEE Std. 1003.1-200x do not conflict on the use of 

8977 environ, but some historical implementations of environ may cause a conflict. As long as environ 

8978 is treated in the same way as an entry point (for example, fork ()), it conforms to both standards. 

8979 A library can contain fork( ), but if there is a user-provided fork( ), that fork( ) is given precedence 

8980 and no problem ensues. The situation is similar for environ: the definition in this volume of 

8981 IEEE Std. 1003.1-200x is to be used if there is no user-provided environ to take precedence. At 

8982 least three implementations are known to exist that solve this problem. 

8983 [E2BIG] The limit |ARG_MAX} applies not just to the size of the argument list, but to 

8984 the sum of that and the size of the environment list. 


8985 [EFAULT] Some historical systems return [EFAULT] rather than [ENOEXEC] when the 

8986 new process image file is corrupted. They are non-conforming. 


8987 

8988 

8989 

8990 

8991 

8992 

8993 

8994 

8995 

8996 

8997 

8998 


[EINVAL] This error condition was added to IEEE Std. 1003.1-200x to allow an 

implementation to detect executable files generated for different architectures, 
and indicate this situation to the application. Historical implementations of 
shells, execvp( ), and exec Ip () that encounter an [ENOEXEC] error will execute 
a shell on the assumption that the file is a shell script. This will not produce 
the desired effect when the file is a valid executable for a different 
architecture. An implementation may now choose to avoid this problem by 
returning [EINVAL] when a valid executable for a different architecture is 
encountered. Some historical implementations return [EINVAL] to indicate 
that the path argument contains a character with the high order bit set. The 
standard developers chose to deviate from historical practice for the following 
reasons: 
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8999 

9000 

9001 

9002 

9003 

9004 

9005 

9006 


1. The new utilization of [EINVAL] will provide some measure of utility to I 

the user community. I 

2. Historical use of [EINVAL] is not acceptable in an internationalized I 

operating environment. I 

[ENAMETOOLONG] I 

Since the file path name may be constructed by taking elements in the PATH 
variable and putting them together with the file name, the 
[ENAMETOOLONG] error condition could also be reached this way. 


9007 [ETXTBSY] System V returns this error when the executable file is currently open for 

9008 writing by some process. This volume of IEEE Std. 1003.1-200x neither 

9009 requires nor prohibits this behavior. 


9010 Other systems (such as System V) may return [EINTR] from exec. This is not addressed by this 

9011 volume of IEEE Std. 1003.1-200x, but implementations may have a window between the call to 

9012 exec and the time that a signal could cause one of the exec calls to return with [EINTR], 


9013 FUTURE DIRECTIONS 

9014 None. 


9015 SEE ALSO 

9016 alarm (), atexit( ), chmod(), close() r exit( ),fcntl(),fork(), fstatvfs{), getenv( ), getitimer( ), getrlimit( ), I 

9017 mmap (), nice(), putenv(), semop(), setlocale(), shmat(), sigaction(), sigaltstack(), sigpending(), 

9018 sigprocmask(), system(), times(), ulimit(), iimask (), the System Interface Definitions volume of 

9019 IEEE Std. 1003.1-200x, <unistd.h>, the System Interface Definitions volume of I 

9020 IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface I 

9021 CHANGE HISTORY 

9022 First released in Issue 1. 

9023 Derived from Issue 1 of the SVID. 


9024 Issue 4 

9025 The <unistd.h> header is added to the SYNOPSIS section. 

9026 The const keyword is added to identifiers of constant type (for example, path,file). 

9027 In the DESCRIPTION: 

9028 • An indication of the disposition of conversion descriptors after a call to one of the exec 

9029 functions is added. 

9030 • A statement about the interaction between exec and atexit( ) is added. 

9031 • usually in the descriptions of argument pointers is removed. 

9032 • oivner ID is changed to user ID. 

9033 • Shared memory is no longer optional. 

9034 • The penultimate paragraph is changed to correct an error in Issue 3. It now refers to "All 

9035 other process attributes ..." instead of "All the process attributes .. 

9036 A note about the initialization of locales is added to the APPLICATION USAGE section. 

9037 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

9038 • In the ERRORS section, the description of the [ENOEXEC] error is changed to indicate that 

9039 this error does not apply to execlp( ) and execvp( ), and the [ENOMEM] error is added. 
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9040 The following change is incorporated for alignment with the FIPS requirements: 

9041 • In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 

9042 name component is larger that |NAME_MAX} is now defined as mandatory and marked as I 

9043 an extension. 


9044 Issue 4, Version 2 

9045 The following changes are incorporated for X/OPEN UNIX conformance: 

9046 • The DESCRIPTION is changed: 

9047 — To indicate the disposition of alternate signal stacks, the SA_ONSTACK flag, and 

9048 mappings established through rnmap () after a successful call to one of the exec functions. 

9049 — The effects of ST_NOSUID being set for a file system are defined. 

9050 — A statement is added that mappings established through rnmap () are not preserved across 

9051 an exec. 

9052 — The list of inherited process attributes is extended to include resource limits, the 

9053 controlling terminal, and interval timers. 

9054 • In the ERRORS section: 

9055 — The condition whereby [ELOOP] is returned if too many symbolic links are encountered 

9056 during path name resolution is defined as mandatory. 

9057 — A second [ENAMETOOLONG] condition is defined that may report excessive length of 

9058 an intermediate result of path name resolution of a symbolic link. 

9059 Issue 5 

9060 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 

9061 Threads Extension. 


9062 Large File Summit extensions are added. 

9063 Issue 6 

9064 The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

9065 • The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 

9066 This is since behavior may vary from one file system to another. 

9067 The following new requirements on POSIX implementations derive from alignment with the 

9068 Single UNIX Specification: 

9069 • In the DESCRIPTION, behavior is defined for when the process image file is not a valid 

9070 executable. 


9071 

9072 

9073 

9074 

9075 

9076 

9077 

9078 

9079 


• In this issue, _POSIX_SAVED_IDS is mandated, thus the effective user ID and effective group 
ID of the new process image shall be saved (as the saved set-user-ID and the saved set- 
group-ID) for use by the setuid() function. 

• The [ELOOP] mandatory error condition is added. 

• A second [ENAMETOOLONG] is added as an optional error condition. 

• The [ETXTBSY] optional error condition is added. 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• The [EINVAL] mandatory error condition is added. 

• The [ELOOP] optional error condition is added. 
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9080 The description of CPU-time clock semantics is added for alignment with I 

9081 IEEE Std. 1003.1d-1999. I 

9082 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by adding semantics I 

9083 for typed memory. I 

9084 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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9085 NAME 

9086 exit, _exit — terminate a process 

9087 SYNOPSIS 

9088 tinclude <stdlib.h> 

9089 void exit (int status) ; 

9090 #include <unistd.h> 

9091 void _exit (int status) ; 

9092 DESCRIPTION 

9093 cx The functionality described on this reference page for the exit() function is aligned with the 

9094 ISO C standard. Any conflict between the requirements described here and the ISO C standard 

9095 are unintentional. This volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 

9096 The exit( ) function shall first call all functions registered by atexit( ), in the reverse order of their 

9097 registration. Each function is called as many times as it was registered. 

9098 If a function registered by a call to atexit( ) fails to return, the remaining registered functions shall 

9099 not be called and the rest of the exit( ) processing shall not be completed. If exit( ) is called more 

9100 than once, the effects are undefined. 

9101 cx The exit ( ) function then flushes all output streams, closes all open streams, and removes all files 

9102 created by tmpfile( ). Finally, control is returned to the host environment as described below. The 

9103 values of status can be EXIT_SUCCESS or EXIT_FAILURE, as described in <stdlib.h>, or any 

9104 cx implementation-dependent value, although note that only the range 0 through 255 shall be 

9105 available to a waiting parent process. 

9106 cx The _exit() and exit{ ) functions shall terminate the calling process with the following 

9107 consequences: 

9108 xsi • All of the file descriptors, directory streams, conversion descriptors, and message catalog 

9109 descriptors open in the calling process are closed. 

9110 xsi • If the parent process of the calling process is executing a zvait (), zvait3 (), zvaitid (), or zvaitpid (), 

9111 and has neither set its SA_NOCLDWAIT flag nor set SIGCHLD to SIG_IGN,it is notified of 

9112 the calling process' termination and the low-order eight bits (that is, bits 0377) of status are 

9113 made available to it. If the parent is not waiting, the child's status shall be made available to 

9114 xsi it when the parent subsequently executes zvait (), zvait3 (), zvaitid (),or zvaitpid (). 

9115 xsi • If the parent process of the calling process is not executing a zvait (), zvait3(), zvaitid (), or 

9116 xsi zvaitpid ( ), and has not set its SA_NOCLDWAIT flag, or set SIGCHLD to SIG_IGN,the calling 

9117 process is transformed into a zombie process. A zombie process is an inactive process and it shall 

9118 xsi be deleted at some later time when its parent process executes zvait (),zvait3(), zvaitid (),or 

9119 zvaitpid (). 

9120 • Termination of a process does not directly terminate its children. The sending of a SIGHUP 

9121 signal as described below indirectly terminates children in some circumstances. 

9122 • If the implementation supports the SIGCHLD signal, a SIGCHLD shall be sent to the parent 

9123 process. 

9124 xsi • If the parent process has set its SA_NOCLDWAIT flag, or set SIGCHLD to SIG_IGN, the 

9125 status shall be discarded, and the lifetime of the calling process shall end immediately. If 

9126 SA_NOCLDWAIT is set, it is implementation-dependent whether a SIGCHLD signal shall be 

9127 sent to the parent process. 
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9128 • The parent process ID of all of the calling process' existing child processes and zombie 

9129 processes is set to the process ID of an implementation-dependent system process. That is, 

9130 these processes are inherited by a special system process. 

9131 xsi • Each attached shared-memory segment is detached and the value of shm_nattch (see 

9132 shmget( )) in the data structure associated with its shared memory ID is decremented by 1. 

9133 xsi • For each semaphore for which the calling process has set a semadj value (see semop ()), that 

9134 value is added to the semval of the specified semaphore. 

9135 • If the process is a controlling process, the SIGHUP signal shall be sent to each process in the 

9136 foreground process group of the controlling terminal belonging to the calling process. 

9137 • If the process is a controlling process, the controlling terminal associated with the session is 

9138 disassociated from the session, allowing it to be acquired by a new controlling process. 

9139 • If the exit of the process causes a process group to become orphaned, and if any member of 

9140 the newly-orphaned process group is stopped, then a SIGHUP signal followed by a 

9141 SIGCONT signal shall be sent to each process in the newly-orphaned process group. 

9142 sem • All open named semaphores in the calling process shall be closed as if by appropriate calls to 

9143 sem_close(). 

9144 ml • Any memory locks established by the process via calls to mlockall () or mlock() shall be 

9145 removed. If locked pages in the address space of the calling process are also mapped into the 

9146 address spaces of other processes and are locked by those processes, the locks established by 

9147 the other processes shall be unaffected by the call by this process to _exit( ). 

9148 mf i shm • Memory mappings created in the process are unmapped before the process is destroyed. 

9149 tym • Any blocks of typed memory that were mapped in the calling process are unmapped, as if I 

9150 nmnmap( ) was implicitly called to unmap them. I 

9151 msg • All open message queue descriptors in the calling process shall be closed as if by appropriate I 

9152 calls to mq_close( ). 

9153 aio • Any outstanding cancelable asynchronous I/O operations may be canceled. Those 

9154 asynchronous I/O operations that are not canceled shall complete as if the _exit() operation 

9155 had not yet occurred, but any associated signal notifications shall be suppressed. The _exit () 

9156 operation itself may block awaiting such I/O completion. Whether any I/O is canceled, and 

9157 which I/O may be canceled upon _exit (), is implementation-dependent. 

9158 • Threads terminated by a call to _exit () shall not invoke their cancelation cleanup handlers or 

9159 per-thread data destructors. 

9160 RETURN VALUE 

9161 These functions do not return. 

9162 ERRORS 

9163 No errors are defined. 
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9164 EXAMPLES 

9165 None. 

9166 APPLICATION USAGE 

9167 Normally applications should use exit () rather than _exit (). 

9168 RATIONALE 

9169 Process Termination 

9170 Early proposals drew a different distinction between normal and abnormal process termination. 

9171 Abnormal termination was caused only by certain signals and resulted in implementation- 

9172 dependent "actions", as discussed below. Subsequent proposals of this volume of 

9173 IEEE Std. 1003.1-200x distinguished three types of termination: normal termination (as in the 

9174 current specification), simple abnormal termination, and abnormal termination with actions. Again 

9175 the distinction between the two types of abnormal termination was that they were caused by 

9176 different signals and that implementation-dependent actions would result in the latter case. 

9177 Given that these actions were completely implementation-dependent, the early proposals were 

9178 only saying when the actions could occur and how their occurrence could be detected, but not 

9179 what they were. This was of little or no use to portable applications, and thus the distinction was 

9180 dropped from this volume of IEEE Std. 1003.1-200x. 

9181 The implementation-dependent actions usually include, in most historical implementations, the 

9182 creation of a file named core in the current working directory of the process. This file contains an 

9183 image of the memory of the process, together with descriptive information about the process, 

9184 perhaps sufficient to reconstruct the state of the process at the receipt of the signal. 

9185 There is a potential security problem in creating a core file if the process was set-user-ID and the 

9186 current user is not the owner of the program, if the process was set-group-ID and none of the 

9187 user's groups match the group of the program, or if the user does not have permission to write in 

9188 the current directory. In this situation, an implementation either should not create a core file or 

9189 should make it unreadable by the user. 

9190 Despite the silence of this volume of IEEE Std. 1003.1-200x on this feature, applications are 

9191 advised not to create files named core because of potential conflicts in many implementations. 

9192 Some historical implementations use a different name than core for the file, such as by 

9193 appending the process ID to the file name. 

9194 Terminating a Process 

9195 It is important that the consequences of process termination as described occur regardless of 

9196 whether the process called _exit () (perhaps indirectly through exit ()) or instead was terminated 

9197 due to a signal or for some other reason. Note that in the specific case of exit () this means that 

9198 the status argument to exit( ) is treated the same as the status argument to _exit( ). 

9199 A language other than C may have other termination primitives than the C-language exit( ) 

9200 function, and programs written in such a language should use its native termination primitives, 

9201 but those should have as part of their function the behavior of _exit() as described. 

9202 Implementations in languages other than C are outside the scope of the present version of this 

9203 volume of IEEE Std. 1003.1-200x, however. 

9204 As required by the ISO C standard, using return from main () is equivalent to calling exit( ) with 

9205 the same argument value. Also, reaching the end of the main () function is equivalent to using 

9206 exit () with an unspecified value. 

9207 A value of zero (or EXIT_SUCCESS, which is required to be zero) for the argument status 

9208 conventionally indicates successful termination. This corresponds to the specification for exit() 
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9209 in the ISO C standard. The convention is followed by utilities such as make and various shells, 

9210 which interpret a zero status from a child process as success. For this reason, applications should 

9211 not call exit(0) or _exit( 0) when they terminate unsuccessfully; for example, in signal-catching 

9212 functions. 

9213 Historically, the implementation-dependent process that inherits children whose parents have 

9214 terminated without waiting on them is called init and has a process ID of 1. 

9215 The sending of a SIGHUP to the foreground process group when a controlling process 

9216 terminates corresponds to somewhat different historical implementations. In System V, the 

9217 kernel sends a SIGHUP on termination of (essentially) a controlling process. In 4.2 BSD, the 

9218 kernel does not send SIGHUP in a case like this, but the termination of a controlling process is 

9219 usually noticed by a system daemon, which arranges to send a SIGHUP to the foreground 

9220 process group with the vhangup () function. However, in 4.2 BSD, due to the behavior of the 

9221 shells that support job control, the controlling process is usually a shell with no other processes 

9222 in its process group. Thus, a change to make _exit( ) behave this way in such systems should not 

9223 cause problems with existing applications. 

9224 The termination of a process may cause a process group to become orphaned in either of two 

9225 ways. The connection of a process group to its parent(s) outside of the group depends on both 

9226 the parents and their children. Thus, a process group may be orphaned by the termination of the 

9227 last connecting parent process outside of the group or by the termination of the last direct 

9228 descendant of the parent process(es). In either case, if the termination of a process causes a 

9229 process group to become orphaned, processes within the group are disconnected from their job 

9230 control shell, which no longer has any information on the existence of the process group. 

9231 Stopped processes within the group would languish forever. In order to avoid this problem, 

9232 newly orphaned process groups that contain stopped processes are sent a SIGHUP signal and a 

9233 SIGCONT signal to indicate that they have been disconnected from their session. The SIGHUP 

9234 signal causes the process group members to terminate unless they are catching or ignoring 

9235 SIGHUP. Under most circumstances, all of the members of the process group are stopped if any 

9236 of them are stopped. 

9237 The action of sending a SIGHUP and a SIGCONT signal to members of a newly orphaned 

9238 process group is similar to the action of 4.2 BSD, which sends SIGHUP and SIGCONT to each 

9239 stopped child of an exiting process. If such children exit in response to the SIGHUP, any 

9240 additional descendants receive similar treatment at that time. In this volume of 

9241 IEEE Std. 1003.1-200x, the signals are sent to the entire process group at the same time. Also, in 

9242 this volume of IEEE Std. 1003.1-200x, but not in 4.2 BSD, stopped processes may be orphaned, 

9243 but may be members of a process group that is not orphaned; therefore, the action taken at 

9244 _exit () must consider processes other than child processes. 

9245 It is possible for a process group to be orphaned by a call to setpgid( ) or setsid (), as well as by 

9246 process termination. This volume of IEEE Std. 1003.1-200x does not require sending SIGHUP 

9247 and SIGCONT in those cases, because, unlike process termination, those cases are not caused 

9248 accidentally by applications that are unaware of job control. An implementation can choose to 

9249 send SIGHUP and SIGCONT in those cases as an extension; such an extension must be 

9250 documented as required in <signal.h>. 

9251 FUTURE DIRECTIONS 

9252 None. 

9253 SEE ALSO 

9254 atexit{), close (), /close (), semop (), shmget(), sigaction{), wait(), waitid(), waitpid(), the System 

9255 Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h>, <unistd.h> 
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9256 CHANGE HISTORY 

9257 First released in Issue 1. 

9258 Derived from Issue 1 of the SVID. 

9259 Issue 4 

9260 The <unistd.h> header is added to the SYNOPSIS for _exit(). 

9261 In the DESCRIPTION, text is added describing the behavior when a function registered by 

9262 atexit( ) fails to return, and the consequences of calling exit( ) more than once. 

9263 The phrase "If the implementation supports job control" is removed from the last bullet in the 

9264 DESCRIPTION. This is because job control is now defined as mandatory for all conforming 

9265 implementations. 

9266 The following change is incorporated for alignment with the ISO C standard: 

9267 • In the DESCRIPTION, interactions between exit() and atexit() are defined, and it is now 

9268 stated explicitly that all files created by tmpfile( ) are removed. 

9269 Issue 4, Version 2 

9270 The following changes to the DESCRIPTION are incorporated for X/OPEN UNIX conformance: 

9271 • References to the functions wait3 () and waitid () are added in appropriate places throughout 

9272 the text. 

9273 • Interactions with the SA_NOCLDWAIT flag and SIGCHLD signal are defined. 

9274 • It is specified that each mapped memory object is unmapped. 

9275 Issue 5 

9276 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 

9277 Threads Extension. 

9278 Interactions with the SA_NOCLDWAIT flag and SIGCHLD signal are further clarified. 

9279 The values of status from exit () are better described. 

9280 Issue 6 

9281 Extensions beyond the ISO C standard are now marked. I 

9282 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by adding semantics I 

9283 for typed memory. I 
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9284 NAME 

9285 exp — exponential function 

9286 SYNOPSIS 

9287 #include <math.h> 

9288 double exp (double x) ; 

9289 DESCRIPTION 

9290 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

9291 conflict between the requirements described here and the ISO C standard is unintentional. This I 

9292 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

9293 The exp() function shall compute the exponent of x, defined as e x . 

9294 An application wishing to check for error situations should set errno to 0 before calling exp( ). If 

9295 errno is non-zero on return, or the return value is NaN, an error has occurred. 

9296 RETURN VALUE 

9297 Upon successful completion, exp( ) shall return the exponential value of x. 

9298 If the correct value would cause overflow, exp() shall return HUGE_VAL and set errno to 

9299 [ERANGE], 

9300 If the correct value would cause underflow, exp( ) shall return 0 and may set errno to [ERANGE]. 

9301 xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

9302 ERRORS 

9303 The exp( ) function shall fail if: 

9304 [ERANGE] The result overflows. 

9305 The exp () function may fail if: 

9306 xsi [EDOM] The value of x is NaN. 

9307 [ERANGE] The result underflows 

9308 xsi No other errors shall occur. 

9309 EXAMPLES 

9310 None. 

9311 APPLICATION USAGE 

9312 None. 

9313 RATIONALE 

9314 None. 

9315 FUTURE DIRECTIONS 

9316 None. 

9317 SEE ALSO 

9318 isnan (), log( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

9319 CHANGE HISTORY 

9320 First released in Issue 1. 

9321 Derived from Issue 1 of the SVID. 
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9322 Issue 4 

9323 References to matherr () are removed. 

9324 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

9325 ISO C standard and to rationalize error handling in the mathematics functions. 

9326 The return value specified for [EDOM] is marked as an extension. 

9327 Issue 5 

9328 The DESCRIPTION is updated to indicate how an application should check for an error. This 

9329 text was previously published in the APPLICATION USAGE section. 
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9330 NAME 

9331 expml — compute exponential functions 

9332 SYNOPSIS 

9333 xsi tinclude <math.h> 

9334 double expml (double x) ; 

9335 

9336 DESCRIPTION 

9337 The expml () function shall compute e x -1.0. 

9338 RETURN VALUE 

9339 If x is NaN, then the function shall return NaN and err no may be set to [EDOM]. 

9340 If x is positive infinity, expml () shall return positive infinity. 

9341 If x is negative infinity, expml () shall return -1.0. 

9342 If the value overflows, expml () shall return HUGE_VAL and may set errno to [ERANGE]. 

9343 ERRORS 

9344 The expml () function may fail if: 

9345 [EDOM] The value of x is NaN. 

9346 [ERANGE] The result overflows. 

9347 EXAMPLES 

9348 None. 

9349 APPLICATION USAGE 

9350 The value of expml (x) may be more accurate than exp(x)-1.0 for small values of x. 

9351 The expml () and loglp () functions are useful for financial calculations of ((l+x)"-l)/x, namely: 

9352 expml (n * loglp(x))/x 

9353 when x is very small (for example, when calculating small daily interest rates). These functions 

9354 also simplify writing accurate inverse hyperbolic functions. 

9355 RATIONALE 

9356 None. 

9357 FUTURE DIRECTIONS 

9358 None. 

9359 SEE ALSO 

9360 exp (), ilogb (), loglp (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

9361 <math.h> 

9362 CHANGE HISTORY 

9363 First released in Issue 4, Version 2. 

9364 Issue 5 

9365 Moved from X/OPEN UNIX extension to BASE. 
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9366 NAME 

9367 fabs — absolute value function 

9368 SYNOPSIS 

9369 #include <math.h> 

9370 double fabs (double x) ; 

9371 DESCRIPTION 

9372 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

9373 conflict between the requirements described here and the ISO C standard is unintentional. This I 

9374 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

9375 The fabs () function shall compute the absolute value of x, I x I. 

9376 An application wishing to check for error situations should set errno to 0 before calling fabs(). If 

9377 errno is non-zero on return, or the return value is NaN, an error has occurred. 

9378 RETURN VALUE 

9379 Upon successful completion, fabs () shall return the absolute value of x. 

9380 xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

9381 If the result underflows, 0 shall be returned and errno may be set to [ERANGE]. 

9382 ERRORS 

9383 The fobs () function may fail if: 

9384 xsi [EDOM] The value of x is NaN. 

9385 [ERANGE] The result underflows 

9386 xsi No other errors shall occur. 

9387 EXAMPLES 

9388 None. 

9389 APPLICATION USAGE 

9390 None. 

9391 RATIONALE 

9392 None. 

9393 FUTURE DIRECTIONS 

9394 None. 

9395 SEE ALSO 

9396 isnan (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

9397 CHANGE HISTORY 

9398 First released in Issue 1. 

9399 Derived from Issue 1 of the SVID. 

9400 Issue 4 

9401 References to matherri ) are removed. 

9402 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

9403 ISO C standard and to rationalize error handling in the mathematics functions. 

9404 The return value specified for [EDOM] is marked as an extension. 
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9405 

9406 

9407 


Issue 5 

The DESCRIPTION is updated to indicate how an application should check for an error. This 
text was previously published in the APPLICATION USAGE section. 
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9408 NAME 

9409 fattach — attach a STREAMS-based file descriptor to a file in the file system name space I 

9410 (STREAMS) I 

9411 SYNOPSIS 

9412 XSR #include <stropts.h> | 

9413 int fattach (int fildes, const char *path) ; 

9414 

9415 DESCRIPTION 

9416 Notes to Reviewers 

9417 This section with side shading will not appear in the final copy. - Ed. 

9418 Re Dl, XSH, ERN 111: if the original file had multiple links, the streams file still has only one? I 

9419 presume that a stream is actually attached to an inode, not a file name. If so, there continue to I 

9420 exist multiple links to the object, even though it shows a link count of 1. If it associated the I 

9421 stream with a file name, then the following sentence is wrong. I 

9422 The fattach () function attaches a STREAMS-based file descriptor to a file, effectively associating 

9423 a path name with fildes. The application shall ensure that the fildes argument is a valid open file I 

9424 descriptor associated with a STREAMS file. The path argument points to a path name of an I 

9425 existing file. The application shall ensure that the process has appropriate privileges, or is the I 

9426 owner of the file named by path and has write permission. A successful call to fattach () shall I 

9427 cause all path names that name the file named by path to name the STREAMS file associated 

9428 with fildes, until the STREAMS file is detached from the file. A STREAMS file can be attached to 

9429 more than one file and can have several path names associated with it. 

9430 The attributes of the named STREAMS file shall be initialized as follows: the permissions, user 

9431 ID, group ID, and times are set to those of the file named by path, the number of links is set to 1, 

9432 and the size and device identifier are set to those of the STREAMS file associated with fildes. If 

9433 any attributes of the named STREAMS file are subsequently changed (for example, by chmod( )), 

9434 neither the attributes of the underlying file nor the attributes of the STREAMS file to which fildes 

9435 refers shall be affected. 

9436 File descriptors referring to the underlying file, opened prior to an fattach () call, shall continue to 

9437 refer to the underlying file. 

9438 RETURN VALUE 

9439 Upon successful completion, fattach () shall return 0. Otherwise, -1 shall be returned and errno 

9440 set to indicate the error. 


9441 ERRORS 

9442 The fattach () function shall fail if: 


9443 

9444 

9445 


[EACCES] Search permission is denied for a component of the path prefix, or the process 

is the owner of path but does not have write permissions on the file named by 
path. 


9446 

9447 

9448 

9449 

9450 


[EBADF] 

[ENOENT] 

[ENOTDIR] 

[EPERM] 


Th e fildes argument is not a valid open file descriptor. 

A component of path does not name an existing file or path is an empty string. 
A component of the path prefix is not a directory. 

The effective user ID of the process is not the owner of the file named by path 
and the process does not have appropriate privilege. 
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9451 [EBUSY] The file named by path is currently a mount point or has a STREAMS file 

9452 attached to it. 

9453 [ENAMETOOLONG] 

9454 The size of path exceeds {PATH_MAX}, or a component of path is longer than 

9455 {NAME_MAX}. 

9456 [ELOOP] Too many symbolic links were encountered in resolving path. 

9457 The /attach () function may fail if: 

9458 [EINVAL] Th efildes argument does not refer to a STREAMS file. 

9459 [ENAMETOOLONG] 

9460 Path name resolution of a symbolic link produced an intermediate result 

9461 whose length exceeds {PATH_MAX}. 

9462 [EXDEV] A link to a file on another file system was attempted. 

9463 EXAMPLES 

9464 Attaching a File Descriptor to a File 

9465 In the following example, fd refers to an open STREAMS file. The call to /attach () associates this 

9466 STREAM with the file /tmp/named-STREAM, such that any future calls to open /tmp/named- 

9467 STREAM, prior to breaking the attachment via a call to fdetach (), will instead create a new file 

9468 handle referring to the STREAMS file associated with/d. 

9469 #include <stropts.h> 

9470 

9471 int fd; 

9472 char *filename = "/tmp/named-STREAM"; 

9473 int ret; 

9474 ret = fattach (fd, filename); 

9475 APPLICATION USAGE 

9476 Th e/attach() function behaves similarly to the traditional mount () function in the way a file is 

9477 temporarily replaced by the root directory of the mounted file system. In the case of fattach (), the 

9478 replaced file need not be a directory and the replacing file is a STREAMS file. 

9479 RATIONALE 

9480 None. 

9481 FUTURE DIRECTIONS 

9482 None. 

9483 SEE ALSO 

9484 /detach (), isastream(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

9485 <stropts.h> 

9486 CHANGE HISTORY 

9487 First released in Issue 4, Version 2. 

9488 Issue 5 

9489 Moved from X/OPEN UNIX extension to BASE. 

9490 The [EXDEV] error is added to the list of optional errors in the ERRORS section. 
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9491 

9492 

9493 


Issue 6 

This function is marked as part of the XSI STREAMS Option Group. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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9494 NAME 

9495 fchdir — change working directory 

9496 Notes to Reviewers 

9497 This section zvith side shading will not appear in the final copy. - Ed. 

9498 This function or these functions are recommended to become mandatory parts of POSIX.l in the 

9499 next draft. 

9500 SYNOPSIS 

9501 xsi tinclude <unistd.h> 

9502 int fchdir (int fildes) ; 

9503 

9504 DESCRIPTION 

9505 Th e fchdir ( ) function has the same effect as chdir( ) except that the directory that is to be the new 

9506 current working directory is specified by the file descriptor fildes . 

9507 RETURN VALUE 

9508 Upon successful completion, fchdir( ) shall return 0. Otherwise, it shall return -1 and set errno to 

9509 indicate the error. On failure the current working directory shall remain unchanged. 

9510 ERRORS 

9511 Th efchdir( ) function shall fail if: 

9512 [EACCES] Search permission is denied for the directory referenced by fildes. 

9513 [EBADF] The fildes argument is not an open file descriptor. 

9514 [ENOTDIR] The open file descriptor fildes does not refer to a directory. 

9515 The fchdir () may fail if: 

9516 [EINTR] A signal was caught during the execution of fchdir (). 

9517 [EIO] An I/O error occurred while reading from or writing to the file system. 

9518 EXAMPLES 

9519 None. 

9520 APPLICATION USAGE 

9521 None. 

9522 RATIONALE 

9523 None. 

9524 FUTURE DIRECTIONS 

9525 None. 

9526 SEE ALSO 

9527 chdir( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

9528 CHANGE HISTORY 

9529 First released in Issue 4, Version 2. 

9530 Issue 5 

9531 Moved from X/OPEN UNIX extension to BASE. 
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9532 NAME 

9533 fchmod — change mode of a file 

9534 SYNOPSIS 

9535 #include <sys/stat.h> 

9536 int fchmod (int fildes, mode_t mode); 

9537 DESCRIPTION 

9538 The fchmod () function has the same effect as chmod () except that the file whose permissions are I 

9539 changed is specified by the file descriptor fildes . I 

9540 shm If fildes references a shared memory object, the fchmod () function need only affect the S_IRUSR, 

9541 SJWUSR, S_IRGRP, S_IWGRP, SJROTH, and S_IWOTH file permission bits. I 

9542 tym If fildes references a typed memory object, the behavior of fchmod () is unspecified. I 

9543 RETURN VALUE 

9544 Upon successful completion , fchmod () shall return 0. Otherwise, it shall return -1 and set err no to 

9545 indicate the error. 

9546 ERRORS 

9547 The fchmod () function shall fail if: 

9548 [EBADF] The fildes argument is not an open file descriptor. 

9549 [EPERM] The effective user ID does not match the owner of the file and the process 

9550 does not have appropriate privilege. 

9551 [EROFS] The file referred to by fildes resides on a read-only file system. 

9552 The fchmod () function may fail if: 

9553 xsi [EINTR] The fchmod () function was interrupted by a signal. 

9554 xsi [EINVAL] The value of the mode argument is invalid. 

9555 [EINVAL] The fildes argument refers to a pipe and the implementation disallows 

9556 execution of fchmod () on a pipe. 

9557 EXAMPLES 

9558 Changing the Current Permissions for a File 

9559 The following example shows how to change the permissions for a file named /home/cnd/modl 

9560 so that the owner and group have read/write/execute permissions, but the world only has 

9561 read /write permissions. 

9562 #include <sys/stat.h> 

9563 #include <fcntl.h> 

9564 mode_t mode; 

9565 int fildes; 

9566 

9567 fildes = open ("/home/cnd/modl " , 0_RDWR) ; 

9568 fchmod (fildes, S_IRWXU | S_IRWXG | S_IROTH | S_IWOTH); 

9569 APPLICATION USAGE 

9570 None. 
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9571 RATIONALE 

9572 None. 

9573 FUTURE DIRECTIONS 

9574 None. 

9575 SEE ALSO 

9576 chmod(), chozvn(), creat(), fcntl(), fstatvfs(), mknod{), open(), read(), stat(), zvrite(), the System 

9577 Interface Definitions volume of IEEE Std. 1003.1-200x, <sys/stat.h> 

9578 CHANGE HISTORY 

9579 First released in Issue 4, Version 2. 

9580 Issue 5 

9581 

9582 

9583 

9584 Issue 6 

9585 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by stating that I 

9586 fchmod () behavior is unspecified for typed memory objects. I 


Moved from X/OPEN UNIX extension to BASE and aligned with fchmod() in the POSIX 
Realtime Extension. Specifically, the second paragraph of the DESCRIPTION is added and a 
second instance of [EINVAL] is defined in the list of optional errors. 
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9587 NAME 

9588 fchown — change owner and group of a file 

9589 Notes to Reviewers 

9590 This section with side shading will not appear in the final copy. - Ed. 

9591 This function or these functions are recommended to become mandatory parts of POSIX.l in the 

9592 next draft. 

9593 SYNOPSIS 

9594 xsi tinclude <unistd.h> 

9595 int fchown (int fildes, uid_t owner, gid_t group); 

9596 

9597 DESCRIPTION 

9598 The fchown () function has the same effect as chown () except that the file whose owner and group I 

9599 are changed is specified by the file descriptor fildes . I 

9600 RETURN VALUE 

9601 Upon successful completion, fchown () shall return 0. Otherwise, it shall return -1 and set errno to 

9602 indicate the error. 


9603 ERRORS 

9604 The fchown () function shall fail if: 


9605 


[EBADF] Th e fildes argument is not an open file descriptor. 


9606 

9607 

9608 


[EPERM] The effective user ID does not match the owner of the file or the process does I 

not have appropriate privilege and _POSIX_CHOWN_RESTRICTED indicates I 
that such privilege is required. I 


9609 


[EROFS] The file referred to by fildes resides on a read-only file system. 


9610 The fchown () function may fail if: 


9611 

[EINVAL] 

The owner or group ID 

9612 


fildes argument refers to 

9613 


fchown () on a pipe. 


is not a value supported by the implementation. The I 
a pipe and the implementation disallows execution of I 


9614 [EIO] A physical I/O error has occurred. 

9615 [EINTR] The fchown () function was interrupted by a signal which was caught. 

9616 EXAMPLES 


9617 Changing the Current Owner of a File 

9618 The following example shows how to change the owner of a file named /home/cnd/modl to 

9619 "jones" and the group to "end”. 

9620 The numeric value for the user ID is obtained by extracting the user ID from the user database 

9621 entry associated with "jones". Similarly, the numeric value for the group ID is obtained by 

9622 extracting the group ID from the group database entry associated with "end". This example 

9623 assumes the calling program has appropriate privileges. 


9624 

9625 

9626 

9627 


#include 

#include 

#include 

#include 


<sys/types.h> 
<unistd.h> 

<fcntl.h> 

<pwd.h> 
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9628 #include <grp.h> 

9629 struct passwd *pwd; 

9630 struct group *grp; 

9631 int tildes; 

9632 

9633 tildes = open ( "/home/cnd/modl " , 0_RDWR) ; 

9634 pwd = getpwnam ( " jones " ) ; 

9635 grp = getgrnam ( " end" ) ; 

9636 fchown (tildes, pwd->pw_uid, grp->gr_gid); 

9637 APPLICATION USAGE 

9638 None. 

9639 RATIONALE 

9640 None. 

9641 FUTURE DIRECTIONS 

9642 None. 

9643 SEE ALSO 

9644 choivn (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

9645 CHANGE HISTORY 

9646 First released in Issue 4, Version 2. 

9647 Issue 5 

9648 Moved from X/OPEN UNIX extension to BASE. 

9649 Issue 6 

9650 The following changes were made to align with the IEEE P1003.1a draft standard: 

9651 • Clarification is added that a call to fchoivn () may not be allowed on a pipe. 


System Interfaces, Issue 6 


305 



fcloseO 


System Interfaces 


9652 NAME 

9653 fclose — close a stream 

9654 SYNOPSIS 

9655 #include <stdio.h> 

9656 int fclose (FILE * stream) ; 

9657 DESCRIPTION 

9658 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

9659 conflict between the requirements described here and the ISO C standard is unintentional. This I 

9660 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

9661 The fclose () function shall cause the stream pointed to by stream to be flushed and the associated 

9662 file to be closed. Any unwritten buffered data for the stream shall be written to the file; any 

9663 unread buffered data shall be discarded. The stream shall be disassociated from the file. If the 

9664 cx associated buffer was automatically allocated, it shall be deallocated. It shall mark for update 

9665 the st_ctime and st_mtime fields of the underlying file, if the stream was writable, and if buffered 

9666 data remains that has not yet been written to the file. The fclose () function shall perform a close () 

9667 on the file descriptor that is associated with the stream pointed to by stream. 

9668 After the call to fclose (), any use of stream causes undefined behavior. 

9669 RETURN VALUE 

9670 cx Upon successful completion, fclose () shall return 0; otherwise, it shall return EOF and set errno to 

9671 indicate the error. 

9672 ERRORS 

9673 The fclose () function shall fail if: 

9674 cx [EAGAIN] The 0_N0NBL0CK flag is set for the file descriptor underlying stream and the 

9675 process would be delayed in the write operation. 

9676 cx [EBADF] The file descriptor underlying stream is not valid. 

9677 cx [EFBIG] An attempt was made to write a file that exceeds the maximum file size. 

9678 xsi [EFBIG] An attempt was made to write a file that exceeds the process' file size limit. 

9679 man [EFBIG] The file is a regular file and an attempt was made to write at or beyond the 

9680 offset maximum associated with the corresponding stream. 

9681 cx [EINTR] The fclose () function was interrupted by a signal. 

9682 cx [EIO] The process is a member of a background process group attempting to write 

9683 to its controlling terminal, TOSTOP is set, the process is neither ignoring nor 

9684 blocking SIGTTOU, and the process group of the process is orphaned. This 

9685 error may also be returned under implementation-dependent conditions. 

9686 cx [ENOSPC] There was no free space remaining on the device containing the file. 

9687 cx [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by 

9688 any process. A SIGPIPE signal shall also be sent to the thread. 

9689 The fclose () function may fail if: 

9690 man [ENXIO] A request was made of a nonexistent device, or the request was outside the 

9691 capabilities of the device. 
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9692 EXAMPLES 

9693 None. 

9694 APPLICATION USAGE 

9695 None. 

9696 RATIONALE 

9697 None. 

9698 FUTURE DIRECTIONS 

9699 None. 

9700 SEE ALSO 

9701 close(), fopen(), getrlimit(), ulimit(), the System Interface Definitions volume of 

9702 IEEE Std. 1003.1-200x, <stdio.h> 

9703 CHANGE HISTORY 

9704 First released in Issue 1. 

9705 Derived from Issue 1 of the SVID. 

9706 Issue 4 

9707 The last sentence of the first paragraph in the DESCRIPTION is changed to say close ( ) instead of 

9708 /close (). This was an error in Issue 3. 

9709 The following paragraph is withdrawn from the DESCRIPTION (by POSIX as well as X/Open) 

9710 because of the possibility of causing applications to malfunction, and the impossibility of 

9711 implementing these mechanisms for pipes: 

9712 If the file is not already at EOF, and the file is one capable of seeking, the file offset of the 

9713 underlying open file description is adjusted so that the next operation on the open file 

9714 description deals with the byte after the last one read from or written to the stream being 

9715 closed. 

9716 It is replaced with a statement that any subsequent use of stream is undefined. 

9717 The [EFBIG] error is marked to indicate the extensions. 

9718 Issue 4, Version 2 

9719 A cross-reference to getrlimit () is added. 

9720 Issue 5 

9721 Large File Summit extensions are added. 

9722 Issue 6 

9723 Extensions beyond the ISO C standard are now marked. 

9724 The following new requirements on POSIX implementations derive from alignment with the 

9725 Single UNIX Specification: 

9726 • The [EFBIG] error is added as part of the large file support extensions. 

9727 • The [ENXIO] optional error condition is added. 
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9728 NAME 

9729 fcntl — file control 

9730 SYNOPSIS 

9731 OH #include <unistd.h> 

9732 #include <fcntl.h> 


9733 int fcntl (int fildes, int cmd, . . .) ; 


9734 DESCRIPTION 

9735 The fcntl () function provides for control over open files. The fildes argument is a file descriptor. 

9736 The available values for cmd are defined in <fcntl.h>, which include: 


9737 

9738 

9739 

9740 

9741 

9742 


F_DUPFD Return a new file descriptor which is the lowest numbered available (that is, 

not already open) file descriptor greater than or equal to the third argument, 
arg, taken as an integer of type int. The new file descriptor refers to the same 
open file description as the original file descriptor, and shares any locks. The 
FD_CLOEXEC flag associated with the new file descriptor is cleared to keep 
the file open across calls to one of the exec functions. 


9743 

9744 

9745 


F_GETFD Get the file descriptor flags defined in <fcntl.h> that are associated with the 

file descriptor fildes . File descriptor flags are associated with a single file 
descriptor and do not affect other file descriptors that refer to the same file. 


9746 F_SETFD 

9747 

9748 

9749 

9750 


Set the file descriptor flags defined in <fcntl.h>, that are associated with fildes, 
to the third argument, arg, taken as type int. If the FD_CLOEXEC flag in the 
third argument is 0, the file shall remain open across the exec functions; 
otherwise, the file shall be closed upon successful execution of one of the exec 
functions. 


9751 

9752 

9753 

9754 

9755 

9756 


F_GETFL Get the file status flags and file access modes, defined in <fcntl.h>, for the file 

description associated with fildes. The file access modes can be extracted from 
the return value using the mask 0_ACCM0DE, which is defined in <fcntl.h>. 
File status flags and file access modes are associated with the file description 
and do not affect other file descriptors that refer to the same file with different 
open file descriptions. 


9757 F_SETFL 

9758 

9759 

9760 

9761 


Set the file status flags, defined in <fcntl.h>, for the file description associated 
with fildes from the corresponding bits in the third argument, arg, taken as 
type int. Bits corresponding to the file access mode and the oflag values that 
are set in arg are ignored. If any bits in arg other than those mentioned here are 
changed by the application, the result is unspecified. 


9762 

9763 

9764 

9765 


F_GETOWN h fildes refers to a socket, get the process or process group ID specified to 
receive SIGURG signals when out-of-band data is available. Positive values 
indicate a process ID; negative values, other than -1, indicate a process group 
ID. If fildes does not refer to a socket, the results are unspecified. 


9766 

9767 

9768 

9769 

9770 


F_SETOWN h fildes refers to a socket, set the process or process group ID specified to 
receive SIGURG signals when out-of-band data is available, using the value of 
the third argument, arg, taken as type int. Positive values indicate a process 
ID; negative values, other than -1, indicate a process group ID. If fildes does 
not refer to a socket, the results are unspecified. 


9771 The following values for cmd are available for advisory record locking. Record locking is 

9772 supported for regular files, and may be supported for other files. 
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F_GETLK Get the first lock which blocks the lock description pointed to by the third 

argument, arg, taken as a pointer to type struct flock, defined in <fcntl.h>. 
The information retrieved overwrites the information passed to fcntl() in the 
structure flock. If no lock is found that would prevent this lock from being 
created, then the structure shall be left unchanged except for the lock type 
which shall be set to F_UNLCK. 

F_SETLK Set or clear a file segment lock according to the lock description pointed to by 

the third argument, arg, taken as a pointer to type struct flock, defined in 
<fcntl.h>. F_SETLK is used to establish shared (or read) locks (F_RDECK) or 
exclusive (or write) locks (F_WRECK), as well as to remove either type of lock 
(F_UNECK). F_RDECK, F_WRECK, and F_UNECK are defined in <fcntl.h>. 
If a shared or exclusive lock cannot be set, shall return immediately 

with a return value of -1. 

F_SETEKW This command is the same as F_SETEK except that if a shared or exclusive 
lock is blocked by other locks, the thread shall wait until the request can be 
satisfied. If a signal that is to be caught is received whil efcntl() is waiting for a 
region, fcntl () shall be interrupted. Upon return from the signal handler, 
fcntl() shall return -1 with errno set to [EINTR], and the lock operation shall 
not be done. 

Additional implementation-dependent values for cmd may be defined in <fcntl.h>. Their names 

shall start with F . 


F SETEKW 


9794 When a shared lock is set on a segment of a file, other processes shall be able to set shared locks 

9795 on that segment or a portion of it. A shared lock prevents any other process from setting an 

9796 exclusive lock on any portion of the protected area. A request for a shared lock shall fail if the 

9797 file descriptor was not opened with read access. 

9798 An exclusive lock shall prevent any other process from setting a shared lock or an exclusive lock 

9799 on any portion of the protected area. A request for an exclusive lock shall fail if the file 

9800 descriptor was not opened with write access. 

9801 The structure flock describes the type ( Ijype ), starting offset [l_whence), relative offset (I_start), 

9802 size (l Jen ), and process ID ( l_pid) of the segment of the file to be affected. 

9803 The value of I_ivlience is {SEEK_SET}, {SEEK_CUR}, or {SEEK_END}, to indicate that the relative 

9804 offset l_start bytes shall be measured from the start of the file, current position, or end of the file, 

9805 man respectively. The value of lJen is the number of consecutive bytes to be locked. The value of 

9806 lJen may be negative (where the definition of off_t permits negative values of lJen). The l_pid 

9807 field is only used with F_GETEK to return the process ID of the process holding a blocking lock. 

9808 After a successful F_GETLK request, when a blocking lock is found, the values returned in the 

9809 flock structure shall be as follows: 


9810 

IJype 

Type of blocking lock found. 

9811 

l_zvhence 

{SEEK_SET}. 

9812 

l_start 

Start of the blocking lock. 

9813 

IJen 

Eength of the blocking lock. 

9814 

l_pid 

Process ID of the process that holds the blocking lock. 


9815 If the command is F_SETEKW and the process must wait for another process to release a lock, 

9816 then the range of bytes to be locked shall be determined before th efcntl() function blocks. If the 

9817 file size or file descriptor seek offset change while fcntl() is blocked, this shall not affect the 

9818 range of bytes locked. 
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9819 man If lJen is positive, the area affected starts at l_start and ends at l_start+ lJen-1. If lJen is I 

9820 negative, the area affected starts at l_start+ lJen and ends at l_start— 1. Locks may start and I 

9821 extend beyond the current end of a file, but the application shall ensure that they are not I 

9822 negative relative to the beginning of the file. A lock shall be set to extend to the largest possible I 

9823 value of the file offset for that file by setting l Jen to 0. If such a lock also has l_start set to 0 and I 

9824 l_zvhence is set to {SEEK_SET}, the whole file shall be locked. 

9825 There shall be at most one type of lock set for each byte in the file. Before a successful return 

9826 from an F_SETLK or an F_SETLKW request when the calling process has previously existing 

9827 locks on bytes in the region specified by the request, the previous lock type for each byte in the 

9828 specified region shall be replaced by the new lock type. As specified above under the 

9829 descriptions of shared locks and exclusive locks, an F_SETLK or an F_SETLKW request 

9830 (respectively) shall fail or block when another process has existing locks on bytes in the specified 

9831 region and the type of any of those locks conflicts with the type specified in the request. 

9832 All locks associated with a file for a given process shall be removed when a file descriptor for 

9833 that file is closed by that process or the process holding that file descriptor terminates. Locks are 

9834 not inherited by a child process. 

9835 A potential for deadlock occurs if a process controlling a locked region is put to sleep by 

9836 attempting to lock another process' locked region. If the system detects that sleeping until a 

9837 locked region is unlocked would cause a deadlock, fcntl () shall fail with an [EDEADLK] error. 

9838 shm When the file descriptor fildes refers to a shared memory object, the behavior of fcntl () shall be 

9839 the same as for a regular file except the effect of the following values for the argument cmd shall 

9840 be unspecified: F_SETFL, F_GETLK, F_SETLK, and F_SETLKW. 

9841 tym If fildes refers to a typed memory object, the result of the fcntl () function is unspecified. I 

9842 man An unlock (F_UNLCK) request in which I Jen is non-zero and the offset of the last byte of the I 

9843 requested segment is the maximum value for an object of type off_t, when the process has an 

9844 existing lock in which l Jen is 0 and which includes the last byte of the requested segment, shall 

9845 be treated as a request to unlock from the start of the requested segment with an l Jen equal to 0. 

9846 Otherwise, an unlock (F_UNLCK) request shall attempt to unlock only the requested segment. 

9847 RETURN VALUE 

9848 Upon successful completion, the value returned shall depend on cmd as follows: 

9849 F_DUPFD A new file descriptor. 

9850 F_GETFD Value of flags defined in <fcntl.h>. The return value shall not be negative. 

9851 F_SETFD Value other than-1. 

9852 F_GETFL Value of file status flags and access modes. The return value is not negative. 

9853 F_SETFL Value other than-1. 

9854 F_GETLK Value other than-1. 

9855 F_SETLK Value other than-1. 

9856 F_SETLKW Value other than-1. I 

9857 F_GETOWN Value of the socket owner process or process group; this will not be-1. I 

9858 F_SETOWN Value other than-1. I 

9859 Otherwise, -1 shall be returned and errno set to indicate the error. 
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9860 ERRORS 

9861 Th efcntl () function shall fail if: 


9862 

9863 

9864 

9865 

9866 

9867 


[EACCES] or [EAGAIN] 

The cmd argument is F_SETLK; the type of lock (Ijype) is a shared (F_RDLCK) 
or exclusive (F_WRLCK) lock and the segment of a file to be locked is already 
exclusive-locked by another process, or the type is an exclusive lock and some 
portion of the segment of a file to be locked is already shared-locked or 
exclusive-locked by another process. 


9868 

9869 

9870 

9871 

9872 


[EBADF] Th efildes argument is not a valid open file descriptor, or the argument cmd is 

F_SETLK or F_SETLKW, the type of lock, l_type, is a shared lock (F_RDLCK), 
and fildes is not a valid file descriptor open for reading, or the type of lock 
Ijype , is an exclusive lock (F_WRLCK), and fildes is not a valid file descriptor 
open for writing. 


9873 [EINTR] 


9874 MAN 

9875 

9876 

9877 


[EINVAL] 


The cmd argument is F_SETLKW and the function was interrupted by a signal. 

The cmd argument is invalid, or the cmd argument is F_DUPFD and arg is 
negative or greater than or equal to |OPEN_MAX}, or the cmd argument is 
F_GETLK, F_SETLK, or F_SETLKW and the data pointed to by arg is not valid, 
or fildes refers to a file that does not support locking. 


9878 

9879 

9880 


[EMFILE] The argument cmd is F_DUPFD and {OPEN_MAX} file descriptors are 

currently open in the calling process, or no file descriptors greater than or 
equal to arg are available. 


9881 

9882 

9883 


[ENOLCK] The argument cmd is F_SETLK or F_SETLKW and satisfying the lock or unlock 

request would result in the number of locked regions in the system exceeding 
a system-imposed limit. 


9884 man [EOVERFLOW] One of the values to be returned cannot be represented correctly. 

9885 man [EOVERFLOW] The cmd argument is F_GETLK, F_SETLK, or F_SETLKW and the smallest or, 

9886 if lJen is non-zero, the largest offset of any byte in the requested segment 

9887 cannot be represented correctly in an object of type off_t. 

9888 Th efcntl () function may fail if: 


9889 [EDEADLK] The cmd argument is F_SETLKW, the lock is blocked by some lock from 

9890 another process and putting the calling process to sleep, waiting for that lock 

9891 to become free would cause a deadlock. 

9892 EXAMPLES 

9893 None. 

9894 APPLICATION USAGE 

9895 None. 

9896 RATIONALE 

9897 The ellipsis in the SYNOPSIS is the syntax specified by the ISO C standard for a variable number 

9898 of arguments. It is used because System V uses pointers for the implementation of file locking 

9899 functions. 

9900 The arg values to F_GETFD, F_SETFD, F_GETFL, and F_SETFL all represent flag values to allow 

9901 for future growth. Applications using these functions should do a read-modify-write operation 

9902 on them, rather than assuming that only the values defined by this volume of 

9903 IEEE Std. 1003.1-200x are valid. It is a common error to forget this, particularly in the case of 

9904 F_SETFD. 
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9905 This volume of IEEE Std. 1003.1-200x permits concurrent read and write access to file data using 

9906 th e fcntl() function; this is a change from the 1984 /usr/group standard and early proposals. 

9907 Without concurrency controls, this feature may not be fully utilized without occasional loss of 

9908 data. Since other mechanisms for creating critical regions, such as semaphores, are not included, 

9909 a file record locking mechanism was thought to be appropriate. The fcntl () mechanism may be 

9910 used to implement semaphores, although access is not first in, first out (FIFO) without extra 

9911 application development effort. 

9912 Data losses occur in several ways. One case occurs when several processes try to update the 

9913 same record, without sequencing controls; several updates may occur in parallel and the last 

9914 writer "wins". Another case is a bit-tree or other internal list-based database that is undergoing 

9915 reorganization. Without exclusive use to the tree segment by the updating process, other reading 

9916 processes chance getting lost in the database when the index blocks are split, condensed, 

9917 inserted, or deleted. While fcntl ( ) is useful for many applications, it is not intended to be overly 

9918 general and does not handle the bit-tree example well. 

9919 This facility is only required for regular files because it is not appropriate for many devices such 

9920 as terminals and network connections. 

9921 Since fcntl () works with "any file descriptor associated with that file, however it is obtained", 

9922 the file descriptor may have been inherited through a fork() or exec operation and thus may 

9923 affect a file that another process also has open. 

9924 The use of the open file description to identify what to lock requires extra calls and presents 

9925 problems if several processes are sharing an open file description, but there are too many 

9926 implementations of the existing mechanism for this volume of IEEE Std. 1003.1-200x to use 

9927 different specifications. 

9928 Another consequence of this model is that closing any file descriptor for a given file (whether or 

9929 not it is the same open file description that created the lock) causes the locks on that file to be 

9930 relinquished for that process. Equivalently, any close for any file/process pair relinquishes the 

9931 locks owned on that file for that process. But note that while an open file description may be 

9932 shared through fork( ), locks are not inherited through fork( ). Yet locks may be inherited through 

9933 one of the exec functions. 

9934 The identification of a machine in a network environment is outside of the scope of this volume 

9935 of IEEE Std. 1003.1-200x. Thus, an l_sysid member, such as found in System V, is not included in 

9936 the locking structure. 

9937 Before successful return from an F_SETLK or F_SETLKW request, the previous lock type for 

9938 each byte in the specified region shall be replaced by the new lock type. This can result in a 

9939 previously locked region being split into smaller regions. If this would cause the number of 

9940 regions being held by all processes in the system to exceed a system-imposed limit, the fcntl () 

9941 function shall return -1 with errno set to [ENOLCK]. 

9942 Mandatory locking was a major feature of the 1984 /usr/group standard. For advisory file 

9943 record locking to be effective, all processes that have access to a file must cooperate and use the 

9944 advisory mechanism before doing I/O on the file. Enforcement-mode record locking is 

9945 important when it cannot be assumed that all processes are cooperating. For example, if one user 

9946 uses an editor to update a file at the same time that a second user executes another process that 

9947 updates the same file and if only one of the two processes is using advisory locking, the 

9948 processes are not cooperating. Enforcement-mode record locking would protect against 

9949 accidental collisions. 

9950 Secondly, advisory record locking requires a process using locking to bracket each I/O operation 

9951 with lock (or test) and unlock operations. With enforcement-mode file and record locking, a 

9952 process can lock the file once and unlock when all I/O operations have been completed. 
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9953 Enforcement-mode record locking provides a base that can be enhanced; for example, with 

9954 sharable locks. That is, the mechanism could be enhanced to allow a process to lock a file so 

9955 other processes could read it, but none of them could write it. 

9956 Mandatory locks were omitted for several reasons: 

9957 1. Mandatory lock setting was done by multiplexing the set-group-ID bit in most 

9958 implementations; this was confusing, at best. 

9959 2. The relationship to file truncation as supported in 4.2 BSD was not well specified. 

9960 3. Any publicly readable file could be locked by anyone. Many historical implementations 

9961 keep the password database in a publicly readable file. A malicious user could thus 

9962 prohibit logins. Another possibility would be to hold open a long-distance telephone line. 

9963 4. Some demand-paged historical implementations offer memory mapped files, and 

9964 enforcement cannot be done on that type of file. 

9965 Since sleeping on a region is interrupted with any signal, alarm () may be used to provide a 

9966 timeout facility in applications requiring it. This is useful in deadlock detection. Because 

9967 implementation of full deadlock detection is not always feasible, the [EDEADLK] error was 

9968 made optional. 

9969 FUTURE DIRECTIONS 

9970 None. 

9971 SEE ALSO 

9972 close (), exec, open (), sigaction (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

9973 <fcntl.h>, <signal.h>, <unistd.h> 

9974 CHANGE HISTORY 

9975 First released in Issue 1. 

9976 Derived from Issue 1 of the SVID. 

9977 Issue 4 

9978 The <sys/types.h> and <unistd.h> headers are now marked as optional (OH); these headers do 

9979 not need to be included on XSI-conformant systems. 

9980 In the DESCRIPTION, sentences describing behavior when lJen is negative are marked as an 

9981 extension, and the description of locks is corrected to make it a requirement on the application. 

9982 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

9983 • In the DESCRIPTION, the meaning of a successful F_SETLK or F_SETLKW request is 

9984 clarified, after a POSIX Request for Interpretation. 

9985 Issue 5 

9986 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 

9987 Threads Extension. 

9988 Large File Summit extensions are added. 

9989 Issue 6 

9990 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

9991 The following new requirements on POSIX implementations derive from alignment with the 

9992 Single UNIX Specification: 

9993 • The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 

9994 required for conforming implementations of previous POSIX specifications, it was not 

9995 required for UNIX applications. 
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9996 

9997 

9998 

9999 

10000 

10001 

10002 

10003 

10004 

10005 

10006 

10007 


• In the DESCRIPTION, sentences describing behavior when lJen is negative are now 
mandated, and the description of unlock (F_UNLOCK) when lJen is non-negative is 
mandated. 

• In the ERRORS section, the [EINVAL] error condition has the case mandated when the cmd is 
invalid, and two [EOVERFLOW] error conditions are added. 

The F_GETOWN and F_SETOWN values are added for sockets. 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• Clarification is added that the extent of the bytes locked is determined prior to the blocking 
action. 

The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that 

fcntl() results are unspecified for typed memory objects. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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10008 NAME 

10009 fcvt — convert a floating-point number to a string (LEGACY) 

10010 SYNOPSIS 

10011 xsi #include <stdlib.h> 

10012 char *fcvt (double value, int ndigit, int *decpt, int *slgn) ; 

10013 

10014 DESCRIPTION 

10015 Refer to ecvt (). 
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10016 NAME 

10017 fdatasync — synchronize the data of a file (REALTIME) 

10018 SYNOPSIS 

10019 SIO tinclude <unistd.h> 

10020 int fdatasync (int fildes) ; 

10021 

10022 DESCRIPTION 

10023 The fdatasync () function shall force all currently queued I/O operations associated with the file 

10024 indicated by file descriptor/z/des to the synchronized I/O completion state. 

10025 The functionality is as described for fsync () (with the symbol _POSIX_SYNCHRONIZED_IO 

10026 defined), with the exception that all I/O operations shall be completed as defined for 

10027 synchronized I/O data integrity completion. 

10028 RETURN VALUE 

10029 If successful, th e fdatasync { ) function shall return the value 0; otherwise, the function shall return 

10030 the value -1 and set errno to indicate the error. If the fdatasync () function fails, outstanding I/O 

10031 operations are not guaranteed to have been completed. 

10032 ERRORS 

10033 The fdatasync () function shall fail if: 

10034 [EBADF] Th e fildes argument is not a valid file descriptor open for writing. 

10035 [EINVAL] This implementation does not support synchronized I/O for this file. 

10036 In the event that any of the queued I/O operations fail, fdatasync () shall return the error 

10037 conditions defined for read() and write (). 

10038 EXAMPLES 

10039 None. 

10040 APPLICATION USAGE 

10041 None. 

10042 RATIONALE 

10043 None. 

10044 FUTURE DIRECTIONS 

10045 None. 

10046 SEE ALSO 

10047 aioJsync{), fentl(), fsync (), open(), read(), write{), the System Interface Definitions volume of 

10048 IEEE Std. 1003.1-200x, <unistd.h> 

10049 CHANGE HISTORY 

10050 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

10051 Issue 6 

10052 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

10053 implementation does not support the _POSIX_SYNCHRONIZED_IO option. 

10054 The fdatasync () function is marked as part of the _POSIX_SYNCHRONIZED_IO option. 
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10055 

10056 

10057 

10058 

10059 

10060 

10061 

10062 

10063 

10064 

10065 

10066 

10067 

10068 

10069 

10070 

10071 

10072 

10073 

10074 

10075 

10076 

10077 

10078 

10079 

10080 
10081 
10082 

10083 

10084 

10085 

10086 

10087 

10088 

10089 

10090 


NAME 

fdetach — detach a name from a STREAMS-based file descriptor (STREAMS) 
SYNOPSIS 

xsr tinclude <stropts.h> 

int fdetach(const char *path); 


DESCRIPTION 

The fdetach () function detaches a STREAMS-based file from the file to which it was attached by a 
previous call to /attach (). The path argument points to the path name of the attached STREAMS 
file. The application shall ensure that the process has appropriate privileges or be the owner of I 
the file. A successful call to fdetach () shall cause all path names that named the attached I 
STREAMS file to again name the file to which the STREAMS file was attached. All subsequent 
operations on path shall operate on the underlying file and not on the STREAMS file. 

All open file descriptions established while the STREAMS file was attached to the file referenced 
by path shall still refer to the STREAMS file after the fdetach () has taken effect. 

If there are no open file descriptors or other references to the STREAMS file, then a successful 
call to fdetach () shall have the same effect as performing the last close( ) on the attached file. 

RETURN VALUE 

Upon successful completion, fdetach () shall return 0; otherwise, it shall return -1 and set errno to 
indicate the error. 


ERRORS 


The fdetach () function shall fail if: 

[EACCES] Search permission is denied on a component of the path prefix. 

[EPERM] The effective user ID is not the owner of path and the process does not have 

appropriate privileges. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of path does not name an existing file or path is an empty string. 

[EINVAL] The path argument names a file that is not currently attached. 

[ENAMETOOLONG] 

The size of a path name exceeds {PATH_MAX}, or a path name component is 
longer than |NAME_MAX}. 

[ELOOP] Too many symbolic links were encountered in resolving path. 

The fdetach () function may fail if: 


[ENAMETOOLONG] 

Path name resolution of a symbolic link produced an intermediate result 
whose length exceeds {PATH_MAX[. 
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10091 EXAMPLES 

10092 Detaching a File 

10093 The following example detaches the STREAMS-based file /tmp/named-STREAM from the file to 

10094 which it was attached by a previous, successful call to /attach (). Subsequent calls to open this 

10095 file refer to the underlying file, not to the STREAMS file. 

10096 #include <stropts.h> 

10097 

10098 char *filename = "/tmp/named-STREAM"; 

10099 int ret; 

10100 ret = fdetach (filename); 

10101 APPLICATION USAGE 

10102 None. 

10103 RATIONALE 

10104 None. 

10105 FUTURE DIRECTIONS 

10106 None. 

10107 SEE ALSO 

10108 /attach (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stropts.h> 

10109 CHANGE HISTORY 

10110 First released in Issue 4, Version 2. 

10111 Issue 5 

10112 Moved from X/OPEN UNIX extension to BASE. 

10113 Issue 6 

10114 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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10115 NAME 

10116 fdopen — associate a stream with a file descriptor 

10117 SYNOPSIS 

10118 tinclude <stdio.h> 

10119 FILE *fdopen(int fildes, const char *mode) ; 

10120 DESCRIPTION 

10121 Th e fdopen () function shall associate a stream with a file descriptor. 

10122 The mode argument is a character string having one of the following values: 

10123 r or rb Open a file for reading. 

10124 zv or zvb Open a file for writing. 

10125 a or ab Open a file for writing at end of file. 

10126 r+ or rb+ or r+b Open a file for update (reading and writing). 

10127 zv+ or zvb+ or zv+b Open a file for update (reading and writing). 

10128 a+ or nb+ or n+b Open a file for update (reading and writing) at end of file. 

10129 The meaning of these flags is exactly as specified in /open (), except that modes beginning with zv 

10130 do not cause truncation of the file. 

10131 Additional values for the mode argument may be supported by an implementation. 

10132 The application shall ensure that the mode of the stream as expressed by the type argument is I 

10133 allowed by the file access mode of the open file description to which fildes refers. The file I 

10134 position indicator associated with the new stream is set to the position indicated by the file I 

10135 offset associated with the file descriptor. I 

10136 The error and end-of-file indicators for the stream shall be cleared. The fdopen () function may 

10137 cause the st_atime field of the underlying file to be marked for update. 

10138 shm If fildes refers to a shared memory object, the result of the fdopen () function is unspecified. 

10139 tym It fildes refers to a typed memory object, the result of the fdopen () function is unspecified. I 

10140 The fdopen () function shall preserve the offset maximum previously set for the open file I 

10141 description corresponding to fildes. 

10142 RETURN VALUE 

10143 Upon successful completion, fdopen () shall return a pointer to a stream; otherwise, a null pointer 

10144 shall be returned and errno set to indicate the error. 

10145 ERRORS 

10146 Th e fdopen () function may fail if: 

10147 [EBADF] The fildes argument is not a valid file descriptor. 

10148 [EINVAL] The mode argument is not a valid mode. 

10149 [EMFILE] |FOPEN_MAX} streams are currently open in the calling process. 

10150 [EMFILE] ]STREAM_MAX] streams are currently open in the calling process. 

10151 [ENOMEM] Insufficient space to allocate a buffer. 
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10152 

10153 

10154 

10155 

10156 

10157 

10158 

10159 

10160 

10161 

10162 

10163 

10164 

10165 

10166 

10167 

10168 

10169 

10170 

10171 

10172 

10173 

10174 

10175 

10176 

10177 

10178 

10179 

10180 
10181 

10182 

10183 

10184 

10185 

10186 

10187 

10188 

10189 

10190 

10191 

10192 

10193 

10194 


EXAMPLES 

None. 

APPLICATION USAGE 

File descriptors are obtained from calls like open (), dnp (), creat( ), or pipe{ ), which open files but 
do not return streams. 

RATIONALE 

The file descriptor may have been obtained from open(), creat(), pipe() r dnp(), or fcntl(); 
inherited through fork( ) or exec; or perhaps obtained by implementation-dependent means, such 
as the 4.3 BSD socket () call. 

The meanings of the type arguments oi fdopen () and /open () differ. With fdopen (), open for write 
(zv or zv+) does not truncate, and append (a or a+) cannot create for writing. There is no need for b 
in the format due to the equivalence of binary and text files in this volume of 
IEEE Std. 1003.1-200x. Although not explicitly required by this volume of IEEE Std. 1003.1-200x, 
a good implementation of append (a) mode would cause the 0_APPEND flag to be set. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

fclose (), /open (), open(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 
<stdio.h>. Section 2.5.1 on page 51 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

In the DESCRIPTION, the use and settings of the mode argument are changed to include binary 
streams and are marked as extensions. 

All errors identified in the ERRORS section are marked as extensions, and the [EMFILE] error is 
added. 

The APPLICATION USAGE section is added. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The type of argument mode is changed from char* to const char*. 

Issue 5 

The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 

Large File Summit extensions are added. 

Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the DESCRIPTION, the use and setting of the mode argument are changed to include 
binary streams. 

• In the DESCRIPTION, text is added for large file support to indicate setting of the offset 
maximum in the open file description. 

• All errors identified in the ERRORS section are added. 

• In the DESCRIPTION, text is added that the fdopen () function may cause st_atime to be I 

updated. I 
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10195 

10196 

10197 

10198 

10199 


The following changes were made to align with the IEEE P1003.1a draft standard: I 

• Clarification is added that it is the responsibility of the application to ensure that the mode is I 
compatible with the open file descriptor. I 

The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that I 
fdopen () results are unspecified for typed memory objects. I 
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10200 NAME 

10201 feof — test end-of-file indicator on a stream 

10202 SYNOPSIS 

10203 tinclude <stdio.h> 

10204 int feof (FILE * stream) ; 

10205 DESCRIPTION 

10206 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

10207 conflict between the requirements described here and the ISO C standard is unintentional. This I 

10208 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

10209 The feof ( ) function shall test the end-of-file indicator for the stream pointed to by stream. 

10210 RETURN VALUE 

10211 The feof () function shall return non-zero if and only if the end-of-file indicator is set for stream. 

10212 ERRORS 

10213 No errors are defined. 

10214 EXAMPLES 

10215 None. 

10216 APPLICATION USAGE 

10217 None. 

10218 RATIONALE 

10219 None. 

10220 FUTURE DIRECTIONS 

10221 None. 

10222 SEE ALSO 

10223 clearerr(), ferror(), fopen(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

10224 <stdio.h> 

10225 CHANGE HISTORY 

10226 First released in Issue 1. 

10227 Derived from Issue 1 of the SVID. 

10228 Issue 4 

10229 The ERRORS section is rewritten, such that no error return values are now defined for this 

10230 function. 
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10231 NAME 

10232 ferror — test error indicator on a stream 

10233 SYNOPSIS 

10234 #include <stdio.h> 

10235 int ferror (FILE * stream); 

10236 DESCRIPTION 

10237 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

10238 conflict between the requirements described here and the ISO C standard is unintentional. This I 

10239 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

10240 The ferror () function shall test the error indicator for the stream pointed to by stream. 

10241 RETURN VALUE 

10242 The ferror ( ) function shall return non-zero if and only if the error indicator is set for stream. 

10243 ERRORS 

10244 No errors are defined. 

10245 EXAMPLES 

10246 None. 

10247 APPLICATION USAGE 

10248 None. 

10249 RATIONALE 

10250 None. 

10251 FUTURE DIRECTIONS 

10252 None. 

10253 SEE ALSO 

10254 clearerr(), feof(), fopen(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

10255 <stdio.h> 

10256 CHANGE HISTORY 

10257 First released in Issue 1. 

10258 Derived from Issue 1 of the SVID. 

10259 Issue 4 

10260 The ERRORS section is rewritten, such that no error return values are now defined for this 

10261 function. 
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10262 NAME 

10263 fflush — flush a stream 

10264 SYNOPSIS 

10265 tinclude <stdio.h> 

10266 int fflush (FILE * stream) ; 

10267 DESCRIPTION 

10268 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

10269 conflict between the requirements described here and the ISO C standard is unintentional. This I 

10270 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

10271 If stream points to an output stream or an update stream in which the most recent operation was 

10272 cx not input, fflush () causes any unwritten data for that stream to be written to the file, and the 

10273 st_ctime and stjntime fields of the underlying file are marked for update. 

10274 If stream is a null pointer , fflush () shall perform this flushing action on all streams for which the 

10275 behavior is defined above. 

10276 RETURN VALUE 

10277 cx Upon successful completion, fflush() shall return 0; otherwise, it shall return EOF and set errno 

10278 to indicate the error. 

10279 ERRORS 

10280 The fflush () function shall fail if: 

10281 cx [EAGAIN] The 0_NONBLOCK flag is set for the file descriptor underlying stream and the 

10282 process would be delayed in the write operation. 

10283 cx [EBADF] The file descriptor underlying stream is not valid. 

10284 cx [EFBIG] An attempt was made to write a file that exceeds the maximum file size. 

10285 xsi [EFBIG] An attempt was made to write a file that exceeds the process' file size limit. 

10286 man [EFBIG] The file is a regular file and an attempt was made to write at or beyond the 

10287 offset maximum associated with the corresponding stream. 

10288 cx [EINTR] Th e fflush () function was interrupted by a signal. 

10289 cx [EIO] The process is a member of a background process group attempting to write 

10290 to its controlling terminal, TOSTOP is set, the process is neither ignoring nor 

10291 blocking SIGTTOU, and the process group of the process is orphaned. This 

10292 error may also be returned under implementation-dependent conditions. 

10293 cx [ENOSPC] There was no free space remaining on the device containing the file. 

10294 cx [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by 

10295 any process. A SIGPIPE signal shall also be sent to the thread. 

10296 The fflush () function may fail if: 

10297 man [ENXIO] A request was made of a nonexistent device, or the request was outside the 

10298 capabilities of the device. 
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10299 EXAMPLES 

10300 Sending Prompts to Standard Output 

10301 The following example uses printf( ) calls to print a series of prompts for information the user 

10302 must enter from standard input. The /flush ( ) calls force the output to standard output. The 

10303 fflush () function is used because standard output is usually buffered and the prompt may not 

10304 immediately be printed on the output or terminal. The gets() calls read strings from standard 

10305 input and place the results in variables, for use later in the program 

10306 tinclude <stdio.h> 

10307 

10308 char user [100]; 

10309 char oldpasswd [ 100 ] ; 

10310 char newpasswd [ 100 ] ; 

10311 

10312 printf ("User name: "); 

10313 fflush (stdout); 

10314 gets (user) ; 

10315 printf ("Old password: "); 

10316 fflush (stdout); 

10317 gets (oldpasswd) ; 

10318 printf ("New password: "); 

10319 fflush (stdout); 

10320 gets (newpasswd) ; 

10321 

10322 APPLICATION USAGE 

10323 None. 

10324 RATIONALE 

10325 Data buffered by the system may make determining the validity of the position of the current I 

10326 file descriptor impractical. Thus, enforcing the repositioning of the file descriptor after fflush () I 

10327 on streams open for read( ) is not mandated by IEEE Std. 1003.1-200x. I 

10328 FUTURE DIRECTIONS 

10329 None. 

10330 SEE ALSO 

10331 getrlimit ( ), ulimit ( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdio.h> 

10332 CHANGE HISTORY 

10333 First released in Issue 1. 

10334 Derived from Issue 1 of the SVID. 

10335 Issue 4 

10336 The following change is incorporated for alignment with the ISO C standard: 

10337 • The DESCRIPTION is changed to describe the behavior of fflush () if stream is a null pointer. 

10338 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

10339 • The following two paragraphs are withdrawn from the DESCRIPTION (by POSIX as well as 

10340 X/Open) because of the possibility of causing applications to malfunction, and the 

10341 impossibility of implementing these mechanisms for pipes: 
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10345 

10346 

10347 

10348 

10349 

10350 

10351 

10352 

10353 

10354 

10355 


If the stream is open for reading, any unread data buffered in the stream is discarded. 

For a stream open for reading, if the file is not already at EOF, and the file is one capable 
of seeking, the file offset of the underlying open file description is adjusted so that the 
next operation on the open file description deals with the byte after the last one read 
from, or written to, the stream being flushed. 

• The [EFBIG] error is marked to indicate the extensions. 


Issue 5 

Large File Summit extensions are added. 


Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The [EFBIG] error is added as part of the large file support extensions. 

• The [ENXIO] optional error condition is added. 
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10356 NAME 

10357 ffs — find first set bit 

10358 Notes to Reviewers 

10359 This section zvith side shading will not appear in the final copy. - Ed. 

10360 This function or these functions are recommended to become mandatory parts of POSIX.l in the 

10361 next draft. 

10362 SYNOPSIS 

10363 xsi tinclude <strings.h> 

10364 int ffs (int i); 

10365 

10366 DESCRIPTION 

10367 The ffs() function shall find the first bit set (beginning with the least significant bit) in i, and 

10368 return the index of that bit. Bits are numbered starting at one (the least significant bit). 

10369 RETURN VALUE 

10370 The ffs () function shall return the index of the first bit set. If i is 0, then ffs () shall return 0. 

10371 ERRORS 

10372 No errors are defined. 

10373 EXAMPLES 

10374 None. 

10375 APPLICATION USAGE 

10376 None. 

10377 RATIONALE 

10378 None. 

10379 FUTURE DIRECTIONS 

10380 None. 

10381 SEE ALSO 

10382 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <strings.h> 

10383 CHANGE HISTORY 

10384 First released in Issue 4, Version 2. 

10385 Issue 5 

10386 Moved from X/OPEN UNIX extension to BASE. 
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10388 

10389 

10390 

10391 

10392 

10393 

10394 

10395 

10396 

10397 

10398 

10399 

10400 

10401 

10402 

10403 

10404 

10405 

10406 

10407 

10408 

10409 

10410 

10411 

10412 

10413 

10414 

10415 

10416 

10417 

10418 

10419 

10420 

10421 

10422 

10423 

10424 

10425 


NAME 

fgetc — get a byte from a stream 

SYNOPSIS 

#include <stdio.h> 

int fgetc(FILE * stream) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The fgetc () function obtains the next byte (if present) as an unsigned char converted to an int, 
from the input stream pointed to by stream, and advances the associated file position indicator 
for the stream (if defined). 

cx The fgetc ( ) function may mark the st_atime field of the file associated with stream for update. The 

st_atime field shall be marked for update by the first successful execution ot fgetc(), fgets(), 
fgetwc(), fgetws(), fread(), fscanfO, getc(), getchar(), gets (), or scanf() using stream that returns 
data not supplied by a prior call to ungetc () or ungetwc {). 

RETURN VALUE 

Upon successful completion, fgetc { ) shall return the next byte from the input stream pointed to 
by stream. If the stream is at end-of-file, the end-of-file indicator for the stream shall be set and 
fgetc () shall return EOF. If a read error occurs, the error indicator for the stream shall be set, 
cx fgetc ( ) shall return EOF, and shall set errno to indicate the error. 

ERRORS 

The fgetc () function shall fail if data needs to be read and: 

cx [EAGAIN] The 0_NONBLOCK flag is set for the file descriptor underlying stream and the 

process would be delayed in the fgetc ( ) operation. 

cx [EBADF] The file descriptor underlying stream is not a valid file descriptor open for 

reading. 

cx [EINTR] The read operation was terminated due to the receipt of a signal, and no data 

was transferred. 

cx [EIO] A physical I/O error has occurred, or the process is in a background process 

group attempting to read from its controlling terminal, and either the process 
is ignoring or blocking the SIGTTIN signal or the process group is orphaned. 
This error may also be generated for implementation-dependent reasons. 

cx [EOVERFLOW] The file is a regular file and an attempt was made to read at or beyond the 

offset maximum associated with the corresponding stream. 

The fgetc ( ) function may fail if: 

cx [ENOMEM] Insufficient storage space is available. 

cx [ENXIO] A request was made of a nonexistent device, or the request was outside the 

capabilities of the device. 


328 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


fgetc() 


10426 EXAMPLES 

10427 None. 

10428 APPLICATION USAGE 

10429 If the integer value returned by fgetc( ) is stored into a variable of type char and then compared 

10430 against the integer constant EOF, the comparison may never succeed, because sign-extension of 

10431 a variable of type char on widening to integer is implementation-dependent. 

10432 The /error () or feof() functions must be used to distinguish between an error condition and an 

10433 end-of-file condition. 

10434 RATIONALE 

10435 None. 

10436 FUTURE DIRECTIONS 

10437 None. 

10438 SEE ALSO 

10439 /eo/(), /error(), fopen(), getchar{), getc(), the System Interface Definitions volume of 

10440 IEEE Std. 1003.1-200x, <stdio.h> 

10441 CHANGE HISTORY 

10442 First released in Issue 1. 

10443 Derived from Issue 1 of the SVID. 

10444 Issue 4 

10445 In the DESCRIPTION: 

10446 • The text is changed to make it clear that the function returns a byte value. 

10447 • The list of functions that may cause the st_atime field to be updated is revised. 

10448 In the ERRORS section, text is added to indicate that error returns are only generated when data 

10449 needs to be read into the stream buffer. 

10450 Also in the ERRORS section, in previous issues generation of the [EIO] error depended on 

10451 whether or not an implementation supported Job Control. This functionality is now defined as 

10452 mandatory. 

10453 The [ENXIO] and [ENOMEM] errors are marked as extensions. 

10454 In the APPLICATION USAGE section, text is added to indicate how an application can 

10455 distinguish between an error condition and an end-of-file condition. 

10456 The description of [EINTR] is amended. 

10457 Issue 4, Version 2 

10458 In the ERRORS section, the description of [EIO] is updated to include the case where a physical 

10459 I/O error occurs. 

10460 Issue 5 

10461 Large File Summit extensions are added. 

10462 Issue 6 

10463 Extensions beyond the ISO C standard are now marked. 

10464 The following new requirements on POSIX implementations derive from alignment with the 

10465 Single UNIX Specification: 

10466 • The [EIO] and [EOVERFLOW] mandatory error conditions are added. 
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• The [ENOMEM] and [ENXIO] optional error conditions are added. 
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10468 NAME 

10469 fgetpos — get current file position information 

10470 SYNOPSIS 

10471 #include <stdio.h> 

10472 int fgetpos (FILE * stream, fpos_t *pos) ; 

10473 DESCRIPTION 

10474 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

10475 conflict between the requirements described here and the ISO C standard is unintentional. This I 

10476 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

10477 The fgetpos () function shall store the current value of the file position indicator for the stream 

10478 pointed to by stream in the object pointed to by pos. The value stored contains unspecified 

10479 information usable by fsetpos() for repositioning the stream to its position at the time of the call 

10480 to fgetpos (). 

10481 RETURN VALUE 

10482 Upon successful completion, fgetpos () shall return 0; otherwise, it shall return a non-zero value 

10483 and set errno to indicate the error. 

10484 ERRORS 

10485 The fgetpos () function shall fail if: 

10486 cx [EOVERFLOW] The current value of the file position cannot be represented correctly in an 

10487 object of type fpos_t. 

10488 The fgetpos () function may fail if: 

10489 cx [EBADF] The file descriptor underlying stream is not valid. 

10490 cx [ESPIPE] The file descriptor underlying stream is associated with a pipe, FIFO, or socket. I 

10491 

10492 EXAMPLES 

10493 None. 

10494 APPLICATION USAGE 

10495 None. 

10496 RATIONALE 

10497 None. 

10498 FUTURE DIRECTIONS 

10499 None. 

10500 SEE ALSO 

10501 fopen(), ftell(), rewind (), ungetc(), the System Interface Definitions volume of 

10502 IEEE Std. 1003.1-200x, <stdio.h> 

10503 CHANGE HISTORY 

10504 First released in Issue 4. 

10505 Derived from the ISO C standard. 

10506 Issue 5 

10507 Large File Summit extensions are added. 
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Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The [EIO] mandatory error condition is added. 

• The [EBADF] and [ESPIPE] optional error conditions are added. 

An additional [ESPIPE] error condition is added for sockets. 
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10515 NAME 

10516 fgets — get a string from a stream 

10517 SYNOPSIS 

10518 tinclude <stdio.h> 

10519 char *fgets (char *s, int n, FILE * stream) ; 

10520 DESCRIPTION 

10521 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

10522 conflict between the requirements described here and the ISO C standard is unintentional. This I 

10523 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

10524 The fgets () function shall read bytes from stream into the array pointed to by s, until n— 1 bytes 

10525 are read, or a <newline> character is read and transferred to s, or an end-of-file condition is 

10526 encountered. The string is then terminated with a null byte. 

10527 cx Th e fgets ( ) function may mark the st_atime field of the file associated with stream for update. The 

10528 st_atime field shall be marked for update by the first successful execution of fgetc(), fgets(), 

10529 fgetwc (), fgetws{ ), fread(), fscanf( ), getc( ), getchar( ), gets(), or scanf( ) using stream that returns 

10530 data not supplied by a prior call to ungetc{ ) or ungetwc{ ). 

10531 RETURN VALUE 

10532 Upon successful completion, fgets () shall return s. If the stream is at end-of-file, the end-of-file 

10533 indicator for the stream shall be set and fgets () shall return a null pointer. If a read error occurs, 

10534 cx the error indicator for the stream shall be set, fgets() shall return a null pointer, and shall set 

10535 errno to indicate the error. 

10536 ERRORS 

10537 Refer to fgetc(). 

10538 EXAMPLES 

10539 Reading Input 

10540 The following example uses fgets( ) to read each line of input. |LINE_MAX}, which defines the 

10541 maximum size of the input line, is defined in the <limits.h> header. 

10542 #include <stdio.h> 

10543 

10544 char line [LINE_MAX] ; 

10545 

10546 while (fgets (line, LINE_MAX, fp) != NULL) { 

10547 

10548 } 

10549 

10550 APPLICATION USAGE 

10551 None. 

10552 RATIONALE 

10553 None. 

10554 FUTURE DIRECTIONS 

10555 None. 
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10562 

10563 

10564 

10565 

10566 

10567 


SEE ALSO 

fopen(), fread (), gets(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

<stdio.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

In the DESCRIPTION, the text is changed to make it clear that the function reads bytes rather 
than (possibly multi-byte) characters, and the list of functions that may cause the st_ativie field to 
be updated is revised. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 
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10568 NAME 

10569 fgetwc — get a wide-character code from a stream 

10570 SYNOPSIS 

10571 #include <stdio.h> 

10572 #include <wchar.h> 

10573 wint_t fgetwc (FILE * stream) ; 

10574 DESCRIPTION 

10575 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

10576 conflict between the requirements described here and the ISO C standard is unintentional. This I 

10577 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

10578 The fgetwc ( ) function shall obtain the next character (if present) from the input stream pointed to 

10579 by stream, convert that to the corresponding wide-character code, and advance the associated 

10580 file position indicator for the stream (if defined). 

10581 If an error occurs, the resulting value of the file position indicator for the stream is 

10582 indeterminate. 

10583 cx The fgetzvc() function may mark the st_atime field of the file associated with stream for update. 

10584 The st_atime field shall be marked for update by the first successful execution of fgetc( ),fgets( ), 

10585 fgetzvc( ), fgetws( ), fread( ), fscanf( ), getc( ), getchar( ), gets( ), or scanf( ) using stream that returns 

10586 data not supplied by a prior call to ungetc( ) or ungetwc (). 

10587 RETURN VALUE 

10588 Upon successful completion, the fgetwc {) function shall return the wide-character code of the 

10589 character read from the input stream pointed to by stream converted to a type wint_t. If the 

10590 stream is at end-of-file, the end-of-file indicator for the stream shall be set and fgetzvc() shall 

10591 return WEOF. If a read error occurs, the error indicator for the stream shall be set , fgetwc () shall 

10592 cx return WEOF, and shall set errno to indicate the error. 

10593 ERRORS 

10594 The fgetzvc( ) function shall fail if data needs to be read and: 

10595 cx [EAGAIN] The 0_NONBLOCK flag is set for the file descriptor underlying stream and the 

10596 process would be delayed in th efgetwc( ) operation. 

10597 cx [EBADF] The file descriptor underlying stream is not a valid file descriptor open for 

10598 reading. 

10599 cx [EINTR] The read operation was terminated due to the receipt of a signal, and no data 

10600 was transferred. 

10601 cx [EIO] A physical I/O error has occurred, or the process is in a background process 

10602 group attempting to read from its controlling terminal, and either the process 

10603 is ignoring or blocking the SIGTTIN signal or the process group is orphaned. 

10604 This error may also be generated for implementation-dependent reasons. 

10605 cx [EOVERFLOW] The file is a regular file and an attempt was made to read at or beyond the 

10606 offset maximum associated with the corresponding stream. 

10607 The fgetzvc( ) function may fail if: 

10608 cx [ENOMEM] Insufficient storage space is available. 

10609 cx [ENXIO] A request was made of a nonexistent device, or the request was outside the 

10610 capabilities of the device. 
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10611 cx [EILSEQ] The data obtained from the input stream does not form a valid character. 

10612 EXAMPLES 

10613 None. 

10614 APPLICATION USAGE 

10615 The /error () or feof{) functions must be used to distinguish between an error condition and an 

10616 end-of-file condition. 

10617 RATIONALE 

10618 None. 

10619 FUTURE DIRECTIONS 

10620 None. 

10621 SEE ALSO 

10622 feof(), /error(), /open (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

10623 <stdio.h>, <wchar.h> 

10624 CHANGE HISTORY 

10625 First released in Issue 4. 

10626 Derived from the MSE working draft. 

10627 Issue 4, Version 2 

10628 In the ERRORS section, the description of [EIO] is updated to include the case where a physical 

10629 I/O error occurs. 

10630 Issue 5 

10631 The Optional Header (OH) marking is removed from <stdio.h>. 

10632 Large File Summit extensions are added. 

10633 Issue 6 

10634 Extensions beyond the ISO C standard are now marked. 

10635 The following new requirements on POSIX implementations derive from alignment with the 

10636 Single UNIX Specification: 

10637 • The [EIO] and [EOVERFLOW] mandatory error conditions are added. 

10638 • The [ENOMEM], [ENXIO], and [EILSEQ] optional error conditions are added. 
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NAME 

fgetws — get a wide-character string from a stream 

SYNOPSIS 

#include <stdio.h> 

#include <wchar.h> 

wchar_t *fgetws(wchar_t *ws, int n, FILE * stream ); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The fgetzvs() function shall read characters from the stream, convert these to the corresponding 
wide-character codes, place them in the wchar_t array pointed to by zvs, until n— 1 characters are 
read, or a <newline> character is read, converted, and transferred to zvs, or an end-of-file 
condition is encountered. The wide-character string, zvs, is then terminated with a null wide- 
character code. 

If an error occurs, the resulting value of the file position indicator for the stream is 
indeterminate. 

cx The fgetzvs( ) function may mark the st_atime field of the file associated with stream for update. 

The st_atime field shall be marked for update by the first successful execution of fgetc(),fgets(), 
fgetzvc (), fgetws (), /read (), fscanf(), getc(), getchar{), gets(), or scanf{) using stream that returns 
data not supplied by a prior call to ungetc( ) or ungetzvc (). 

RETURN VALUE 

Upon successful completion, fgetzvs() shall return zvs. If the stream is at end-of-file, the end-of- 
file indicator for the stream shall be set and fgetzvs() shall return a null pointer. If a read error 
cx occurs, the error indicator for the stream shall be set , fgetws () shall return a null pointer, and 

shall set errno to indicate the error. 

ERRORS 

Refer to fgetzvc (). 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

ftopen (), /read (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <stdio.h>, 
<wchar.h> 

CHANGE HISTORY 

First released in Issue 4. 

Derived from the MSE working draft. 
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Issue 5 

The Optional Header (OH) marking is removed from <stdio.h>. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 
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10685 NAME 

10686 fileno — map a stream pointer to a file descriptor 

10687 SYNOPSIS 

10688 tinclude <stdio.h> 

10689 int fileno (FILE * stream) ; 

10690 DESCRIPTION 

10691 Th e fileno () function shall return the integer file descriptor associated with the stream pointed to 

10692 by stream. 

10693 RETURN VALUE 

10694 Upon successful completion, fileno () shall return the integer value of the file descriptor 

10695 associated with stream. Otherwise, the value -1 shall be returned and errno set to indicate the 

10696 error. 

10697 ERRORS 

10698 Th e fileno () function may fail if: 

10699 man [EBADF] The stream argument is not a valid stream. 

10700 EXAMPLES 

10701 None. 

10702 APPLICATION USAGE 

10703 None. 

10704 RATIONALE 

10705 Without some specification of which file descriptors are associated with these streams, it is 

10706 impossible for an application to set up the streams for another application it starts with fork() 

10707 and exec. In particular, it would not be possible to write a portable version of the sh command 

10708 interpreter (although there may be other constraints that would prevent that portability). 

10709 FUTURE DIRECTIONS 

10710 None. 

10711 SEE ALSO 

10712 fdopen{), fopen{), stdin, the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

10713 <stdio.h>. Section 2.5.1 on page 51 

10714 CHANGE HISTORY 

10715 First released in Issue 1. 

10716 Derived from Issue 1 of the SVID. 

10717 Issue 4 

10718 The [EBADF] error is marked as an extension. 

10719 Issue 6 

10720 The following new requirements on POSIX implementations derive from alignment with the 

10721 Single UNIX Specification: 

10722 • The [EBADF] optional error condition is added. 
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10723 NAME 

10724 flockfile, ftrylockfile, funlockfile — stdio locking functions 

10725 SYNOPSIS 

10726 TSF #include <stdio.h> 

10727 

10728 

10729 

10730 

10731 DESCRIPTION 

10732 The flockfile(), ftrylockfile (), and funlockfile () functions provide for explicit application-level 

10733 locking of stdio (FILE 51 ') objects. These functions can be used by a thread to delineate a sequence I 

10734 of I/O statements that are executed as a unit. I 

10735 The flockfile () function is used by a thread to acquire ownership of a (FILE*) object. 

10736 The ftrylockfile() function is used by a thread to acquire ownership of a (FILE*) object if the 

10737 object is available; ftrylockfile () is a non-blocking version of flockfile (). 

10738 The funlockfile () function is used to relinquish the ownership granted to the thread. The 

10739 behavior is undefined if a thread other than the current owner calls the funlockfile () function. 

10740 Logically, there is a lock count associated with each (FILE*) object. This count is implicitly 

10741 initialized to zero when the (FILE*) object is created. The (FILE*) object is unlocked when the 

10742 count is zero. When the count is positive, a single thread owns the (FILE*) object. When the 

10743 flockfile () function is called, if the count is zero or if the count is positive and the caller owns the 

10744 (FILE*) object, the count is incremented. Otherwise, the calling thread is suspended, waiting for 

10745 the count to return to zero. Each call to funlockfile () decrements the count. This allows matching 

10746 calls to flockfile () (or successful calls to ftrylockfile ()) and funlockfile () to be nested. 

10747 All functions that reference (FILE*) objects shall behave as if they us e flockfile () and funlockfile () 

10748 internally to obtain ownership of these (FILE*) objects. 

10749 RETURN VALUE 

10750 None for flockfile () and funlockfile (). The ftrylockfile () function shall return zero for success and 

10751 non-zero to indicate that the lock cannot be acquired. 

10752 ERRORS 

10753 No errors are defined. 

10754 EXAMPLES 

10755 None. 

10756 APPLICATION USAGE 

10757 Applications using these functions may be subject to priority inversion, as discussed in the I 

10758 System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.290, Priority Inversion. I 

10759 RATIONALE 

10760 The flockfile () and funlockfile () functions provide an orthogonal mutual exclusion lock for each 

10761 FILE. The ftrylockfile () function provides a non-blocking attempt to acquire a file lock, 

10762 analogous to pthreaci_mutex_trylock (). 

10763 These locks behave as if they are the same as those used internally by stdio for thread-safety. 

10764 This both provides thread-safety of these functions without requiring a second level of internal 

10765 locking and allows functions in stdio to be implemented in terms of other stdio functions. 

10766 Application writers and implementors should be aware that there are potential deadlock 

10767 problems on FILE objects. For example, the line-buffered flushing semantics of stdio (requested 


void flockfile(FILE * file) ; 
int ftrylockfile(FILE * file) ; 
void funlockfile(FILE * file) ; 
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10768 via {_IOLBF}) require that certain input operations sometimes cause the buffered contents of 

10769 implementation-dependent line-buffered output streams to be flushed. If two threads each hold 

10770 the lock on the other's FILE, deadlock ensues. This type of deadlock can be avoided by acquiring 

10771 FILE locks in a consistent order. In particular, the line-buffered output stream deadlock can 

10772 typically be avoided by acquiring locks on input streams before locks on output streams if a 

10773 thread would be acquiring both. 

10774 In summary, threads sharing stdio streams with other threads can use flockfile ( ) and funlockfile () 

10775 to cause sequences of I/O performed by a single thread to be kept bundled. The only case where 

10776 the use of flockfile () and funlockfile () is required is to provide a scope protecting uses of the 

10777 *_nnlocked() functions/macros. This moves the cost/performance tradeoff to the optimal point. 

10778 FUTURE DIRECTIONS 

10779 None. 

10780 SEE ALSO 

10781 getc_unlocked(), putc_unlocked(), the System Interface Definitions volume of 

10782 IEEE Std. 1003.1-200x, <stdio.h> 

10783 CHANGE HISTORY 

10784 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

10785 Issue 6 

10786 These functions are marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS option. 
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10787 NAME 

10788 floor — floor function 

10789 SYNOPSIS 

10790 tinclude <math.h> 

10791 double floor (double x) ; 

10792 DESCRIPTION 

10793 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

10794 conflict between the requirements described here and the ISO C standard is unintentional. This I 

10795 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

10796 The floor () function shall compute the largest integral value not greater than x. 

10797 An application wishing to check for error situations should set errno to 0 before calling floor ( ). If 

10798 errno is non-zero on return, or the return value is NaN, an error has occurred. 

10799 RETURN VALUE 

10800 Upon successful completion, floor ( ) shall return the largest integral value not greater than x, 

10801 expressed as a double. 

10802 xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

10803 If the correct value would cause overflow, -HUGE_VAL shall be returned and errno set to 

10804 [ERANGE]. 

10805 xsi If x is ±Inf or ±0, the value of x shall be returned. 

10806 ERRORS 

10807 The floor ( ) function shall fail if: 

10808 [ERANGE] The result would cause an overflow. 

10809 The floor () function may fail if: 

10810 xsi [EDOM] The value of x is NaN. 

10811 xsi No other errors shall occur. 

10812 EXAMPLES 

10813 None. 

10814 APPLICATION USAGE 

10815 The integral value returned by floor () as a double might not be expressible as an int or long int. 

10816 The return value should be tested before assigning it to an integer type to avoid the undefined 

10817 results of an integer overflow. 

10818 The floor () function can only overflow when the floating point representation has 

10819 DBL_MANT_DIG > DBL_MAX_EXP. 

10820 RATIONALE 

10821 None. 

10822 FUTURE DIRECTIONS 

10823 None. 

10824 SEE ALSO 

10825 ceil (), is nan (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 
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10826 CHANGE HISTORY 

10827 First released in Issue 1. 

10828 Derived from Issue 1 of the SVID. 

10829 Issue 4 

10830 References to matherr {) are removed. 

10831 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

10832 ISO C standard and to rationalize handling in the mathematics functions. 

10833 The word long has been replaced with the words long int in the APPLICATION USAGE section. 

10834 The return value specified for [EDOM] is marked as an extension. 

10835 Issue 5 

10836 The DESCRIPTION is updated to indicate how an application should check for an error. This 

10837 text was previously published in the APPLICATION USAGE section. 
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10838 NAME 

10839 fmod — floating-point remainder value function 

10840 SYNOPSIS 

10841 #include <math.h> 

10842 double fmod (double x, double y) ; 

10843 DESCRIPTION 

10844 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

10845 conflict between the requirements described here and the ISO C standard is unintentional. This I 

10846 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

10847 The fmod () function shall return the floating-point remainder of the division of x by y. 

10848 An application wishing to check for error situations should set errno to 0 before calling fmod (). If 

10849 errno is non-zero on return, or the return value is NaN, an error has occurred. 

10850 RETURN VALUE 

10851 The/mod () function shall return the value x-i*y, for some integer i such that, if y is non-zero, the 

10852 result has the same sign as x and magnitude less than the magnitude of y. 

10853 xsi If x or y is NaN, NaN shall be returned and errno may be set to [EDOM]. 

10854 xsi If y is 0,NaN shall be returned and errno set to [EDOM], or 0 shall be returned and errno may be 

10855 set to [EDOM], 

10856 xsi If x is ±Inf, either 0 shall be returned and errno set to [EDOM], or NaN shall be returned and errno 

10857 may be set to [EDOM]. 

10858 If y is non-zero, fmod (±0,y) shall return the value of x. If x is not ±Inf, fmod (x,±Inf) shall return 

10859 the value of x. 

10860 If the result underflows, 0 shall be returned and errno may be set to [ERANGE]. 

10861 ERRORS 

10862 The fmod () function may fail if: 

10863 xsi [EDOM] One or both of the arguments is NaN, or y is 0, or x is ±Inf. 

10864 [ERANGE] The result underflows 

10865 xsi No other errors shall occur. 

10866 EXAMPLES 

10867 None. 

10868 APPLICATION USAGE 

10869 Portable applications should not call fmod() with y equal to 0, because the result is 

10870 implementation-dependent. The application should verify y is non-zero before calling fmod (). 

10871 RATIONALE 

10872 None. 

10873 FUTURE DIRECTIONS 

10874 None. 

10875 SEE ALSO 

10876 isnan (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 
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10877 CHANGE HISTORY 

10878 First released in Issue 1. 

10879 Derived from Issue 1 of the SVID. 

10880 Issue 4 

10881 References to matherr {) are removed. 

10882 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

10883 ISO C standard and to rationalize error handling in the mathematics functions. 

10884 The return value specified for [EDOM] is marked as an extension. 


10885 Issue 5 

10886 The DESCRIPTION is updated to indicate how an application should check for an error. This 

10887 text was previously published in the APPLICATION USAGE section. 
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10888 NAME 

10889 fmtmsg — display a message in the specified format on standard error and/or a system console 

10890 SYNOPSIS 

10891 xsi tinclude <fmtmsg.h> 

10892 

10893 

10894 


int fmtmsg(long classification, const char * label, int severity, 
const char *text, const char * action, const char *tag); 


10895 DESCRIPTION 

10896 The fmtmsg( ) function can be used to display messages in a specified format instead of the 

10897 traditional printfi ) function. 

10898 

10899 

Based on a message's classification component, fmtmsg () writes a formatted message either to 
standard error, to the console, or to both. 

10900 

10901 

10902 

A formatted message consists of up to five components as defined below. The component 
classification is not part of a message displayed to the user, but defines the source of the message 
and directs the display of the formatted message. 

10903 

10904 

10905 

10906 

10907 

10908 

10909 

classification 

Contains identifiers from the following groups of major classifications and 
subclassifications. Any one identifier from a subclass may be used in 
combination with a single identifier from a different subclass. Two or more 
identifiers from the same subclass should not be used together, with the 
exception of identifiers from the display subclass. (Both display subclass 
identifiers may be used so that messages can be displayed to both standard 
error and the system console). 

10910 

10911 

10912 


Major Classifications 

Identifies the source of the condition. Identifiers are: MM_HARD 
(hardware), MM_SOFT (software), and MM_FIRM (firmware). 

10913 

10914 

10915 

10916 


Message Source Subclassifications 

Identifies the type of software in which the problem is detected. 
Identifiers are: MM_APPL (application), MM_UTIL (utility), and 
MM_OPSYS (operating system). 

10917 

10918 

10919 

10920 

10921 


Display Subclassifications 

Indicates where the message is to be displayed. Identifiers are: 
MM_PRINT to display the message on the standard error stream, 
MM_CONSOLE to display the message on the system console. One or 
both identifiers may be used. 

10922 

10923 

10924 

10925 


Status Subclassifications 

Indicates whether the application can recover from the condition. 
Identifiers are: MM_RECOVER (recoverable) and MM_NRECOV (non- 
recoverable). 

10926 

10927 


An additional identifier, MM_NULLMC, indicates that no classification 
component is supplied for the message. 

10928 

10929 

label 

Identifies the source of the message. The format is two fields separated by a 
colon. The first field is up to 10 bytes, the second is up to 14 bytes. 

10930 

10931 

severity 

Indicates the seriousness of the condition. Identifiers for the levels of severity 
are: 
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10932 

10933 


MM_HALT 

Indicates that the application has encountered a severe fault 
and is halting. Produces the string " HALT". 

10934 

10935 


MM_ERROR 

Indicates that the application has detected a fault. Produces 
the string "ERROR". 

10936 

10937 

10938 


MM_WARNING 

Indicates a condition that is out of the ordinary, that might 
be a problem, and should be watched. Produces the string 

"WARNING". 

10939 

10940 


MMJNFO 

Provides information about a condition that is not in error. 
Produces the string " INFO". 

10941 


MM_NOSEV 

Indicates that no severity level is supplied for the message. 

10942 

10943 

10944 

text 

Describes the error condition that produced the message. The character string 
is not limited to a specific size. If the character string is empty, then the text 
produced is unspecified. 

10945 

10946 

10947 

action 

Describes the first step to be taken in the error-recovery process. The fmtmsg () 
function precedes the action string with the prefix: "TO FIX: ". The action 
string is not limited to a specific size. 

10948 

10949 

10950 

tag 

An identifier that references on-line documentation for the message. 
Suggested usage is that tag includes the label and a unique identifying number. 
A sample tag is " XS I : cat : 1 4 6 ". 


10951 The MSGVERB environment variable (for message verbosity) tells fmtmsg( ) which message 

10952 components it is to select when writing messages to standard error. The value of MSGVERB is a 

10953 colon-separated list of optional keywords. Valid keywords are: label, severity, text, action, and tag. If 

10954 MSGVERB contains a keyword for a component and the component's value is not the 

10955 component's null value, fmtmsg( ) includes that component in the message when writing the 

10956 message to standard error. If MSGVERB does not include a keyword for a message component, 

10957 that component is not included in the display of the message. The keywords may appear in any 

10958 order. If MSGVERB is not defined, if its value is the null string, if its value is not of the correct 

10959 format, or if it contains key wo rd s other than the valid ones listed above, fmtmsg( ) selects all 

10960 components. 

10961 MSGVERB affects only which components are selected for display to standard error. All 

10962 message components are included in console messages. 

10963 RETURN VALUE 


10964 

Th efmtmsg () function shall return one of the following values: 


10965 

MM_OK 

The function succeeded. 


10966 

MM_NOTOK 

The function failed completely. 


10967 

10968 

MM_NOMSG 

The function was unable to generate a message on standard 
otherwise succeeded. 

error, but 

10969 

10970 

MM_NOCON 

The function was unable to generate a console message, but 
succeeded. 

otherwise 

10971 ERRORS 

10972 None. 
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10973 EXAMPLES 

10974 1. The following example of fmtmsg (): 

10975 fmtmsg (MM_PRINT, "XSI:cat", MM_ERROR, "illegal option", 

10976 "refer to cat in user's reference manual", "XSI: cat: 001" ) 

10977 produces a complete message in the specified message format: 

10978 XSI: cat: ERROR: illegal option 

10979 TO FIX: refer to cat in user's reference manual XSI: cat: 001 

10980 2. When the environment variable MSGVERB is set as follows: 

10981 MSGVERB=severity : text: action 

10982 and Example 1 is used, fmtmsg( ) produces: 

10983 ERROR: illegal option 

10984 TO FIX: refer to cat in user's reference manual 

10985 APPLICATION USAGE 

10986 One or more message components may be systematically omitted from messages generated by 

10987 an application by using the null value of the argument for that component. 

10988 RATIONALE 

10989 None. 

10990 FUTURE DIRECTIONS 

10991 None. 

10992 SEE ALSO 

10993 printf( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <fmtmsg.h> 

10994 CHANGE HISTORY 

10995 First released in Issue 4, Version 2. 

10996 Issue 5 

10997 Moved from X/OPEN UNIX extension to BASE. 
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10998 NAME 

10999 fnmatch — match a file name or a path name 

11000 SYNOPSIS 

11001 tinclude <fnmatch.h> 

11002 int fnmatch (const char * pattern, const char * string, int flags); 

11003 DESCRIPTION 

11004 The fnmatch () function shall match patterns as described in the Commands and Utilities volume 

11005 of IEEE Std. 1003.1-200x, Section 2.13.1, Patterns Matching a Single Character, and Section 2.13.2, 

11006 Patterns Matching Multiple Characters. It checks the string specified by the string argument to 

11007 see if it matches the pattern specified by the pattern argument. 

11008 Th e flags argument modifies the interpretation of pattern and string. It is the bitwise-inclusive OR 

11009 of zero or more of the flags defined in <fnmatch.h>. If the FNM_PATHNAME flag is set in flags, 

11010 then a slash character (' /') in string shall be explicitly matched by a slash in pattern; it shall not 

11011 be matched by either the asterisk or question-mark special characters, nor by a bracket 

11012 expression. If the FNM_PATHNAME flag is not set, the slash character is treated as an ordinary 

11013 character. 

11014 If FNM_NOESCAPE is not set in flags, a backslash character (' V ) in pattern followed by any 

11015 other character shall match that second character in string. In particular, "\\" shall match a 

11016 backslash in string. If FNM_NOESCAPE is set, a backslash character shall be treated as an 

11017 ordinary character. 

11018 If FNM_PERIOD is set in flags, then a leading period (' .') in string shall match a period in 

11019 pattern; as described by rule 2 in the Commands and Utilities volume of IEEE Std. 1003.1-200x, 

11020 Section 2.13.3, Patterns Used for File Name Expansion where the location of "leading" is 

11021 indicated by the value of FNM_PATHNAME: 

11022 • If FNM_PATHNAME is set, a period is "leading" if it is the first character in string or if it 

11023 immediately follows a slash. 

11024 • If FNM_PATHNAME is not set, a period is "leading" only if it is the first character of string. 

11025 If FNM_PERIOD is not set, then no special restrictions are placed on matching a period. 

11026 RETURN VALUE 

11027 If string matches the pattern specified by pattern, then fnmatch () shall return 0. If there is no 

11028 match, fnmatch () shall return FNM_NOMATCH, which is defined in <fnmatch.h>. If an error 

11029 occurs, fnmatch () shall return another non-zero value. 

11030 ERRORS 

11031 No errors are defined. 

11032 EXAMPLES 

11033 None. 

11034 APPLICATION USAGE 

11035 Th e fnmatch() function has two major uses. It could be used by an application or utility that 

11036 needs to read a directory and apply a pattern against each entry. The find utility is an example of 

11037 this. It can also be used by the pax utility to process its pattern operands, or by applications that 

11038 need to match strings in a similar manner. 

11039 The nam e fnmatch() is intended to imply file name match, rather than path name match. The 

11040 default action of this function is to match file names, rather than path names, since it gives no 

11041 special significance to the slash character. With the FNM_PATHNAME flag , fnmatch() does 

11042 match path names, but without tilde expansion, parameter expansion, or special treatment for a 
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11043 period at the beginning of a file name. 

11044 RATIONALE 

11045 This function replaced the REG_FILENAME flag of regcomp() in early proposals of this volume 

11046 of IEEE Std. 1003.l-200x. It provides virtually the same functionality as the regcomp () and 

11047 regexec( ) functions using the REG_FILENAME and REG_FSLASH flags (the REG_FSLASH flag 

11048 was proposed for regcomp (), and would have had the opposite effect from FNM_PATHNAME), 

11049 but with a simpler function and less system overhead. 

11050 FUTURE DIRECTIONS 

11051 None. 

11052 SEE ALSO 

11053 gtob(), wordexp (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

11054 <fnmatch.h>, the Commands and Utilities volume of IEEE Std. 1003.1-200x 

11055 CHANGE HISTORY 

11056 First released in Issue 4. 

11057 Derived from the ISO POSIX-2 standard. 

11058 Issue 5 

11059 Moved from POSIX2 C-language Binding to BASE. 
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11060 NAME 

11061 fopen — open a stream 

11062 SYNOPSIS 

11063 tinclude <stdio.h> 

11064 FILE *fopen(const char * filename, const char *mode) ; 

11065 DESCRIPTION 

11066 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

11067 conflict between the requirements described here and the ISO C standard is unintentional. This I 

11068 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

11069 The fopen () function shall open the file whose path name is the string pointed to by filename , and 

11070 associates a stream with it. 

11071 The argument mode points to a string beginning with one of the following sequences: 

11072 r or rb Open file for reading. 

11073 zv or zvb Truncate to zero length or create file for writing. 

11074 a or ab Append; open or create file for writing at end-of-file. 

11075 r+ or rb+ or r+b Open file for update (reading and writing). 

11076 zv+ or zvb+ or zv+b Truncate to zero length or create file for update. 

11077 a+ or ab+ or n+b Append; open or create file for update, writing at end-of-file. 

11078 cx The character ' b' has no effect, but is allowed for ISO C standard conformance. Opening a file 

11079 with read mode (r as the first character in the mode argument) shall fail if the file does not exist or 

11080 cannot be read. 

11081 Opening a file with append mode (a as the first character in the mode argument) shall cause all 

11082 subsequent writes to the file to be forced to the then current end-of-file, regardless of intervening 

11083 calls to fseek( ). 

11084 When a file is opened with update mode (' +' as the second or third character in the mode 

11085 argument), both input and output may be performed on the associated stream. However, the I 

11086 application shall ensure that output is not directly followed by input without an intervening call I 

11087 to /flush () or to a file positioning function (fseek( ),fsetpos (), or rezvind ()), and input is not directly I 

11088 followed by output without an intervening call to a file positioning function, unless the input I 

11089 operation encounters end-of-file. I 

11090 When opened, a stream is fully buffered if and only if it can be determined not to refer to an 

11091 interactive device. The error and end-of-file indicators for the stream shall be cleared. 

11092 cx If mode is zv, a, zv+, or n+, and the file did not previously exist, upon successful completion, 

11093 fopen () function shall mark for update the st_atime, st_ctime, and st_mtime fields of the file and 

11094 the st_ctime and st_mtime fields of the parent directory. 

11095 If mode is zv or zv+ and the file did previously exist, upon successful completion, fopen () shall 

11096 mark for update the st_ctime and st_mtime fields of the file. The fopen () function shall allocate a 

11097 file descriptor as open () does. 

11098 xsi After a successful call to the fopen () function, the orientation of the stream shall be cleared, the 

11099 encoding rule shall be cleared, and the associated mbstate_t object shall be set to describe an 

11100 initial conversion state. 

11101 The largest value that can be represented correctly in an object of type off_t shall be established 

11102 as the offset maximum in the open file description. 
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11103 

11104 

11105 

11106 

11107 

11108 

11109 

11110 
mil 

11112 

11113 

11114 

11115 

11116 

11117 

11118 

11119 

11120 
11121 

11122 

11123 

11124 

11125 

11126 

11127 

11128 

11129 

11130 

11131 

11132 

11133 

11134 

11135 

11136 

11137 

11138 

11139 

11140 


RETURN VALUE 

Upon successful completion, fopen () shall return a pointer to the object controlling the stream, 
cx Otherwise, a null pointer shall be returned, and errno shall be set to indicate the error. 

ERRORS 

The /open () function shall fail if: 

cx [EACCES] Search permission is denied on a component of the path prefix, or the file 

exists and the permissions specified by mode are denied, or the file does not 
exist and write permission is denied for the parent directory of the file to be 
created. 

cx [EINTR] A signal was caught during/open (). 

cx [EISDIR] The named file is a directory and mode requires write access, 

cx [ELOOP] Too many symbolic links were encountered in resolving path. 

cx [EMFILE] |OPEN_MAX} file descriptors are currently open in the calling process, 

cx [ENAMETOOLONG] 

The length of the filename exceeds {PATH_MAX} or a path name component is 
longer than |NAME_MAX} while _POSIX_NO_TRUNC is in effect. 

cx [ENFILE] The maximum allowable number of files is currently open in the system. 

cx [ENOENT] A component of filename does not name an existing file or filename is an empty 

string. 

cx [ENOSPC] The directory or file system that would contain the new file cannot be 

expanded, the file does not exist, and it was to be created. 

cx [ENOTDIR] A component of the path prefix is not a directory. 

cx [ENXIO] The named file is a character special or block special file, and the device 

associated with this special file does not exist. 

cx [EOVERFLOW] The named file is a regular file and the size of the file cannot be represented 

correctly in an object of type off_t. 

cx [EROFS] The named file resides on a read-only file system and mode requires write 

access. 

Th efopen () function may fail if: 

cx [EINVAL] The value of the mode argument is not valid, 

cx [EMFILE] [FOPEN_MAX[ streams are currently open in the calling process, 

cx [EMFILE] [STREAM_MAX[ streams are currently open in the calling process, 

cx [ENAMETOOLONG] 

Path name resolution of a symbolic link produced an intermediate result 
whose length exceeds [PATH_MAX[. 

cx [ENOMEM] Insufficient storage space is available. 

cx [ETXTBSY] The file is a pure procedure (shared text) file that is being executed and mode 

requires write access. 
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11141 EXAMPLES 

11142 Opening a File 

11143 The following example tries to open the file named file for reading. Th efopen() function shall 

11144 return a file pointer that will be used in subsequent /gets () and /close () calls. If the program 

11145 cannot open the file, it just ignores it. 

11146 #include <stdio.h> 

11147 

11148 FILE *fp; 

11149 

11150 void rgrep (const char *file) 

11151 { 

11152 

11153 if ( (fp = fopen (file, "r")) == NULL) 

11154 return; 

11155 

11156 } 

11157 APPLICATION USAGE 

11158 None. 

11159 RATIONALE 

11160 None. 

11161 FUTURE DIRECTIONS 

11162 None. 

11163 SEE ALSO 

11164 f close (), fdopen(), f reopen (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

11165 <stdio.h> 

11166 CHANGE HISTORY 

11167 First released in Issue 1. 

11168 Derived from Issue 1 of the SVID. 

11169 Issue 4 

11170 In the DESCRIPTION, the descriptions of input and output operations on update streams are 

11171 changed to be requirements on the application. 

11172 The [EMFILE] error is added to the ERRORS section, and all the optional errors are marked as 

11173 extensions. 

11174 The following changes are incorporated for alignment with the ISO C standard: 

11175 • The type of arguments filename and mode are changed from char* to const char*. 

11176 • In the DESCRIPTION, the use and settings of the mode argument are changed to support 

11177 binary streams, and setpos( ) is added to the list of file positioning functions. 

11178 The following change is incorporated for alignment with the FIPS requirements: 

11179 • In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 

11180 name component is larger that |NAME_MAX} is now defined as mandatory and marked as 

11181 an extension. 
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11182 

11183 

11184 

11185 

11186 

11187 

11188 

11189 

11190 

11191 

11192 

11193 

11194 

11195 

11196 

11197 

11198 

11199 

11200 

11201 

11202 

11203 

11204 


Issue 4, Version 2 

The ERRORS section is updated for X/OPEN UNIX conformance as follows: 

• It states that [ELOOP] is returned if too many symbolic links are encountered during path 
name resolution. 

• A second [ENAMETOOLONG] condition is defined that may report excessive length of an 
intermediate result of path name resolution of a symbolic link. 

Issue 5 

Large File Summit extensions are added. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 
This is since behavior may vary from one file system to another. 

The following new requirements on POSIX implementations derive from alignment with the 

Single UNIX Specification: 

• In the DESCRIPTION, text is added to indicate setting of the offset maximum in the open file 
description. This change is to support large files. 

• In the ERRORS section, the [EOVERFLOW] condition is added. This change is to support 
large files. 

• The [ELOOP] mandatory error condition is added. 

. The [EINVAL], [EMFILE], [ENAMETOOLONG], [ENOMEM], and [ETXTBSY] optional error 
conditions are added. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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11205 

11206 

11207 

11208 

11209 

11210 
11211 
11212 

11213 

11214 

11215 

11216 

11217 

11218 

11219 

11220 
11221 
11222 

11223 

11224 

11225 

11226 

11227 

11228 

11229 

11230 

11231 

11232 

11233 

11234 

11235 

11236 

11237 

11238 

11239 

11240 

11241 

11242 

11243 

11244 

11245 

11246 


NAME 

fork — create a new process 

SYNOPSIS 

#include <unistd.h> 


pid_t fork(void); 


DESCRIPTION 

Th efork () function creates a new process. The new process (child process) shall be an exact copy 
of the calling process (parent process) except as detailed below: 


xsi 


XSI 


XSI 

SEM 

ML 

MFISHM 


PS 


TMR 

MSG 


• The child process has a unique process ID. 

• The child process ID also does not match any active process group ID. 

• The child process has a different parent process ID (that is, the process ID of the parent 
process). 

• The child process has its own copy of the parent's file descriptors. Each of the child's file 
descriptors refers to the same open file description with the corresponding file descriptor of 
the parent. 

• The child process has its own copy of the parent's open directory streams. Each open 
directory stream in the child process may share directory stream positioning with the 
corresponding directory stream of the parent. 

• The child process may have its own copy of the parent's message catalog descriptors. 

• The child process' values of tms_utime, tms_stime, tms_cutime, and tms_cstime are set to 0. 

• The time left until an alarm clock signal is reset to zero, and the alarm, if any, is canceled; see I 

alarm (). I 

• All s emadj values are cleared. 

• File locks set by the parent process are not inherited by the child process. 

• The set of signals pending for the child process is initialized to the empty set. 

• Interval timers are reset in the child process. 

• Any semaphores that are open in the parent process shall also be open in the child process. 

• The child process does not inherit any address space memory locks established by the parent 
process via calls to mlockall () or mlock( ). 

• Memory mappings created in the parent are retained in the child process. MAP_PRIVATE 
mappings inherited from the parent shall also be MAP_PRIVATE mappings in the child, and 
any modifications to the data in these mappings made by the parent prior to calling fork() 
shall be visible to the child. Any modifications to the data in MAP_PRIVATE mappings made 
by the parent after fork( ) returns shall be visible only to the parent. Modifications to the data 
in MAP_PRIVATE mappings made by the child shall be visible only to the child. 

• For the SCHED_FIFO and SCHED_RR scheduling policies, the child process shall inherit the 
policy and priority settings of the parent process during a fork() function. For other 
scheduling policies, the policy and priority settings on fork () are implementation-dependent. 

• Per-process timers created by the parent are not inherited by the child process. 

• The child process has its own copy of the message queue descriptors of the parent. Each of 
the message descriptors of the child refers to the same open message queue description as 
the corresponding message descriptor of the parent. 
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11247 aio • No asynchronous input or asynchronous output operations are inherited by the child 

11248 process. 

11249 • A process is created with a single thread. If a multi-threaded process calls fork(), the new 

11250 process contains a replica of the calling thread and its entire address space, possibly 

11251 including the states of mutexes and other resources. Consequently, to avoid errors, the child 

11252 process may only execute async-signal-safe operations until such time as one of the exec 

11253 thr functions is called. Fork handlers may be established by means of the pthread_atfork() 

11254 function in order to maintain application invariants across fork( ) calls. 

11255 cpt The initial value of the CPU-time clock of the child process shall be set to zero. I 

11256 tct The initial value of the CPU-time clock of the single thread of the child process shall be set to I 

11257 zero. I 

11258 Notes to Reviewers I 

11259 This section with side shading will not appear in the final copy. - Ed. 

11260 Check this text is correct after new addenda are rolled in. (Ref Dl, XSH, ERN 126) 

11261 For process characteristics not defined by this volume of IEEE Std. 1003.1-200x, their inheritance 

11262 is not defined by this volume of IEEE Std. 1003.1-200x. Process characteristics defined by this 

11263 volume of IEEE Std. 1003.1-200x have their inheritance explicitly defined. 

11264 Alter fork (), both the parent and the child processes are capable of executing independently 

11265 before either one terminates. 

11266 RETURN VALUE 

11267 Upon successful completion , fork() shall return 0 to the child process and shall return the 

11268 process ID of the child process to the parent process. Both processes shall continue to execute 

11269 from the fork( ) function. Otherwise, -1 shall be returned to the parent process, no child process 

11270 shall be created, and errno shall be set to indicate the error. 

11271 ERRORS 

11272 The fork( ) function shall fail if: 

11273 [E AG AIN] The system lacked the necessary resources to create another process, or the 

11274 system-imposed limit on the total number of processes under execution 

11275 system-wide or by a single user ]CHILD_MAX} would be exceeded. 

11276 The fork( ) function may fail if: 

11277 [ENOMEM] Insufficient storage space is available. 

11278 EXAMPLES 

11279 None. 

11280 APPLICATION USAGE 

11281 None. 

11282 RATIONALE 

11283 Many historical implementations have timing windows where a signal sent to a process group 

11284 (for example, an interactive SIGINT) just prior to or during execution otfork( ) is delivered to the 

11285 parent following the fork () but not to the child because the fork () code clears the child's set of 

11286 pending signals. This volume of IEEE Std. 1003.1-200x does not require, or even permit, this 

11287 behavior. Flowever, it is pragmatic to expect that problems of this nature may continue to exist 

11288 in implementations that appear to conform to this volume of IEEE Std. 1003.1-200x and pass 

11289 available verification suites. This behavior is only a consequence of the implementation failing to 

11290 make the interval between signal generation and delivery totally invisible. From the 
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application's perspective, a fork{) call should appear atomic. A signal that is generated prior to 
the fork () should be delivered prior to th e fork (). A signal sent to the process group after the 
fork( ) should be delivered to both parent and child. The implementation may actually initialize 
internal data structures corresponding to the child's set of pending signals to include signals 
sent to the process group during the fork (). Since the fork () call can be considered as atomic 
from the application's perspective, the set would be initialized as empty and such signals would 
have arrived after the fork (); see also <signal.h>. 

One approach that has been suggested to address the problem of signal inheritance across fork () 
is to add an [EINTR] error, which would be returned when a signal is detected during the call. 
While this is preferable to losing signals, it was not considered an optimal solution. Although it 
is not recommended for this purpose, such an error would be an allowable extension for an 
implementation. 

The [ENOMEM] error value is reserved for those implementations that detect and distinguish 
such a condition. This condition occurs when an implementation detects that there is not enough 
memory to create the process. This is intended to be returned when [E AG AIN] is inappropriate 
because there can never be enough memory (either primary or secondary storage) to perform the 
operation. Because fork() duplicates an existing process, this must be a condition where there is 
sufficient memory for one such process, but not for two. Many historical implementations 
actually return [ENOMEM] due to temporary lack of memory, a case that is not generally 
distinct from [EAGAIN] from the perspective of a portable application. 

Part of the reason for including the optional error [ENOMEM] is because the SVID specifies it 
and it should be reserved for the error condition specified there. The condition is not applicable 
on many implementations. 

The original language did not adequately convey the requirement. The effect should be the same I 
as that produced by the call alarm ( 0). Pending signals (those generated for and blocked by a I 
process), including SIGALRM, are discussed in the DESCRIPTION. I 

IEEE Std. 1003.1-1988 neglected to require concurrent execution of the parent and child otfork (). I 
A system that single-threads processes was clearly not intended and is considered an 
unacceptable "toy implementation" of this volume of IEEE Std. 1003.1-200x. The only objection 
anticipated to the phrase "executing independently" is testability, but this assertion should be 
testable. Such tests require that both the parent and child can block on a detectable action of the 
other, such as a write to a pipe or a signal. An interactive exchange of such actions should be 
possible for the system to conform to the intent of this volume of IEEE Std. 1003.1-200x. 

The [EAGAIN] error exists to warn applications that such a condition might occur. Whether it 
occurs or not is not in any practical sense under the control of the application because the 
condition is usually a consequence of the user's use of the system, not of the application's code. 
Thus, no application can or should rely upon its occurrence under any circumstances, nor 
should the exact semantics of what concept of "user" is used be of concern to the application 
writer. Validation writers should be cognizant of this limitation. 

There are two reasons why POSIX programmers call fork( ). One reason is to create a new thread 
of control within the same program (which was originally only possible in POSIX by creating a 
new process); the other is to create a new process running a different program. In the latter case, 
the call to fork( ) is soon followed by a call to one of the exec functions. 

The general problem with making fork() work in a multi-threaded world is what to do with all 
of the threads. There are two alternatives. One is to copy all of the threads into the new process. 
This causes the programmer or implementation to deal with threads that are suspended on 
system calls or that might be about to execute system calls that should not be executed in the 
new process. The other alternative is to copy only the thread that calls fork (). This creates the 
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11339 difficulty that the state of process-local resources is usually held in process memory. If a thread 

11340 that is not calling fork () holds a resource, that resource is never released in the child process 

11341 because the thread whose job it is to release the resource does not exist in the child process. 

11342 When a programmer is writing a multi-threaded program, the first described use ot fork (), 

11343 creating new threads in the same program, is provided by the pthread_create() function. The 

11344 fork( ) function is thus used only to run new programs, and the effects of calling functions that 

11345 require certain resources between the call to fork( ) and the call to an exec function are undefined. 

11346 A cleaner and easier alternative is to define a single new operation that combines the fork () and 

11347 exec functions and the miscellaneous code between them that sets up the new process state. This 

11348 was considered to be too large a departure from standard practice. 

11349 The addition of th eforkall ( ) function to the standard was considered and rejected. Th eforkall () 

11350 function lets all the threads in the parent be duplicated in the child. This essentially duplicates 

11351 the state of the parent in the child. This allows threads in the child to continue processing and 

11352 allows locks and the state to be preserved without explicit pthread_atfork() code. The calling 

11353 process has to ensure that the threads processing state that is shared between the parent and 

11354 child (that is, file descriptors or MAP_SHARED memory) behaves properly after forkall ( ). For 

11355 example, if a thread is reading a file descriptor in the parent when forkall () is called, then two 

11356 threads (one in the parent and one in the child) are reading the file descriptor after th eforkall (). 

11357 If this is not desired behavior, the parent process has to synchronize with such threads before 

11358 calling/orfaz//(). 

11359 When forkall () is called, threads, other than the calling thread, that are in POSIX System 

11360 Interfaces functions that can return with an [EINTR] error may have those functions return 

11361 [EINTR] if the implementation cannot ensure that the function behaves correctly in the parent 

11362 and child. In particular, pthread_cond_zvait () and pthread_cond_timedwait{ ) need to return in order 

11363 to ensure that the condition has not changed. These functions can be awakened by a spurious 

11364 condition wakeup rather than returning [EINTR]. 

11365 FUTURE DIRECTIONS 

11366 None. 

11367 SEE ALSO 

11368 alarm (), exec, fcntl(), semop(), signal (), times(), the System Interface Definitions volume of 

11369 IEEE Std. 1003.1-200x, <sys/types.h>, <unistd.h> 

11370 CHANGE HISTORY 

11371 First released in Issue 1. 

11372 Derived from Issue 1 of the SVID. 

11373 Issue 4 

11374 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

11375 XSI-conformant systems. 

11376 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

11377 • The argument list is explicitly defined as void. 

11378 • Though functionally identical to Issue 3, the DESCRIPTION has been reorganized to improve 

11379 clarity and to align more closely with the ISO POSIX-1 standard. 

11380 • The description of the [EAGAIN] error is updated to indicate that this error can also be 

11381 returned if a system lacks the resources to create another process. 
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11389 

11390 

11391 

11392 

11393 

11394 

11395 

11396 

11397 


Issue 4, Version 2 

The DESCRIPTION is changed for X/OPEN UNIX conformance to identify that interval timers 
are reset in the child process. 

Issue 5 

The DESCRIPTION is changed for alignment with the POSIX Realtime Extension and the POSIX 
Threads Extension. 


Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

The following changes were made to align with the IEEE P1003.1a draft standard: I 

• The effect of fork () on a pending alarm call in the child process is clarified. I 

The description of CPU-time clock semantics is added for alignment with I 
IEEE Std. 1003.1d-1999. I 
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11398 NAME 

11399 fpathconf, pathconf — get configurable path name variables 

11400 SYNOPSIS 

11401 tinclude <unistd.h> 

11402 long int fpathconf (int fildes, int name) ; 

11403 long int pathconf (const char *path, int name) ; 

11404 DESCRIPTION 

11405 The fpathconf () and pathconf () functions provide a method for the application to determine the 

11406 current value of a configurable limit or option ( variable ) that is associated with a file or directory. 

11407 For pathconf (), the path argument points to the path name of a file or directory. 

11408 For fpathconf '(), the fildes argument is an open file descriptor. 

11409 The name argument represents the variable to be queried relative to that file or directory. 

11410 Implementations shall support all of the variables listed in the following table and may support 

11411 others. The variables in the following table come from <limits.h> or <unistd.h> and the 

11412 symbolic constants, defined in <unistd.h>, are the corresponding values used for name. Support I 

11413 for some path name configuration variables is dependent on implementation options (see I 

11414 shading and margin codes in the table below). Where an implementation option is not I 


11415 supported, the variable need not be supported. 

11416 


11417 

Variable 

Value of name 

Notes 

11418 MAN 

jFILESIZEBITS) 

_PC_FILESIZEBITS 

3,4 

11419 

|LINK_MAX} 

_PC_LINK_MAX 

1 

11420 

|MAX_CANON) 

_PC_MAX_CANON 

2 

11421 

|MAX_INPUT[ 

PC MAX INPUT 

2 

11422 

|NAME_MAX) 

_PC_N AME_M AX 

3,4 

11423 

|PATH_MAX} 

PC PATH MAX 

4,5 

11424 

|PIPE_BUF} 

_PC_PIPE_BUF 

6 

11425 ADV 

j POSIX_ALLOC_SIZE_MIN [ 

_PC_ALLOC_SIZE_MIN 


11426 ADV 

j POSIX_REC_INCR_XFER_SIZE [ 

_PC_REC_INCR_XFER_SIZE 


11427 ADV 

j POSIX_REC_M AX_XFER_SIZE} 

PC RFC MAX XFER SIZE 


11428 ADV 

|POSIX_REC_MIN_XFER_SIZE[ 

_PC_REC_MIN_XFER_SIZE 


11429 ADV 

{POSIX_REC_XFER_ ALIGN} 

_PC_REC_XFER_ALIGN 


11430 

| S YMLINK_M AX} 

_PC_SYMLINK_MAX 

4,9 

11431 

_POSIX_CHOWN_RESTRICTED 

PC CHOWN RESTRICTED 

7 

11432 

_POSIX_NO_TRUNC 

_PC_NO_TRUNC 

3,4 

11433 

_POSIX_VDISABLE 

_PC_VDISABLE 

2 

11434 

_POSIX_ASYNC_IO 

_PC_ASYNC_IO 

8 

11435 

_POSIX_PRIO_IO 

_PC_PRIO_IO 

8 

11436 

POSIX SYNC IO 

PC SYNC IO 

8 






11437 Notes: 

11438 1. If path or fildes refers to a directory, the value returned applies to the directory 

11439 itself. 

11440 2. If path or fildes does not refer to a terminal file, it is unspecified whether an 

11441 implementation supports an association of the variable name with the specified 

11442 file. 
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3. If path or fildes refers to a directory, the value returned applies to file names 
within the directory. 

4. If path or fildes does not refer to a directory, it is unspecified whether an 
implementation supports an association of the variable name with the specified 
file. 

5. If path or fildes refers to a directory, the value returned is the maximum length 
of a relative path name when the specified directory is the working directory. 

6. If path refers to a FIFO, or fildes refers to a pipe or FIFO, the value returned 
applies to the referenced object. If path or fildes refers to a directory, the value 
returned applies to any FIFO that exists or can be created within the directory. 

If path or fildes refers to any other type of file, it is unspecified whether an 
implementation supports an association of the variable name with the specified 
file. 

7. If path or fildes refers to a directory, the value returned applies to any files, other 
than directories, that exist or can be created within the directory. 

8. If path or fildes refers to a directory, it is unspecified whether an implementation 

supports an association of the variable name with the specified file. I 

9. If path or fildes refers to a directory, the value returned is the maximum length I 

of the string that a symbolic link in that directory can contain. I 

RETURN VALUE 

If name is an invalid value, both pathconf( ) and fpathconf ( ) shall return -1 and set errno to 
indicate the error. 

If the variable corresponding to name has no limit for the path or file descriptor, both pathconf( ) 
and fpathconf () shall return -1 without changing errno. If the implementation needs to use path 
to determine the value of name and the implementation does not support the association of name 
with the file specified by path , or if the process did not have appropriate privileges to query the 
file specified by path , or path does not exist, pathconf( ) shall return -1 and set errno to indicate the 
error. 

If the implementation needs to use fildes to determine the value of name and the implementation 
does not support the association of name with the file specified by fildes, or it fildes is an invalid 
file descriptor, fpathconf ( ) shall return -1 and set errno to indicate the error. 

Otherwise, pathconf( ) or fpathconf ( ) shall return the current variable value for the file or 
directory without changing errno. The value returned shall not be more restrictive than the 
corresponding value available to the application when it was compiled with the 
implementation's <limits.h> or <unistd.h>. 

ERRORS 

The pathconf( ) function shall fail if: 

[EINVAL] The value of name is not valid. 

man [ELOOP] A loop exists in symbolic links encountered during resolution of the path I 

argument. I 

The pathconf( ) function may fail if: 

[EACCES] Search permission is denied for a component of the path prefix. 

[EINVAL] The implementation does not support an association of the variable name with 

the specified file. I 


System Interfaces, Issue 6 


361 



fpathconf () 


System Interfaces 


11487 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during 

11488 resolution of the path argument. 

11489 [ENAMETOOLONG] 

11490 The length of the path argument exceeds {PATH_MAX} or a path name 

11491 component is longer than |NAME_MAX} while _POSIX_NO_TRUNC is in 

11492 effect. 

11493 MAN 

11494 

11495 

11496 [ENOENT] A component of path does not name an existing file or path is an empty string. 

11497 [ENOTDIR] A component of the path prefix is not a directory. 

11498 Th e fpathconf ( ) function shall fail if: 

11499 [EINVAL] The value of name is not valid. 

11500 The fpathconf () function may fail if: 

11501 [EBADF] Th efildes argument is not a valid file descriptor. 

11502 [EINVAL] The implementation does not support an association of the variable name with 

11503 the specified file. 

11504 EXAMPLES 

11505 None. 

11506 APPLICATION USAGE 

11507 None. 

11508 RATIONALE 

11509 The pathconfO function was proposed immediately after the sysconfO function when it was 

11510 realized that some configurable values may differ across file system, directory, or device 

11511 boundaries. 

11512 For example, [NAME_MAX[ frequently changes between System V and BSD-based file systems; I 

11513 System V uses a maximum of 14, BSD 255. On an implementation that provides both types of file 

11514 systems, an application would be forced to limit all path name components to 14 bytes, as this 

11515 would be the value specified in <limits.h> on such a system. 

11516 Therefore, various useful values can be queried on any path name or file descriptor, assuming 

11517 that the appropriate permissions are in place. 

11518 The value returned for the variable {PATH_MAX} indicates the longest relative path name that I 

11519 could be given if the specified directory is the process' current working directory. A process may 

11520 not always be able to generate a name that long and use it if a subdirectory in the path name 

11521 crosses into a more restrictive file system. 

11522 The value returned for the variable _POSIX_CHOWN_RESTRICTED also applies to directories 

11523 that do not have file systems mounted on them. The value may change when crossing a mount 

11524 point, so applications that need to know should check for each directory. (An even easier check 

11525 is to try the chown () function and look for an error in case it happens.) 

11526 Unlike the values returned by sysconf( ), the path name-oriented variables are potentially more 

11527 volatile and are not guaranteed to remain constant throughout the process' lifetime. For 

11528 example, in between two calls to pathconfO, the file system in question may have been 

11529 unmounted and remounted with different characteristics. 


[ENAMETOOLONG] 

As a result of encounering a symbolic link in resolution of the path argument, 
the length of the substituted path name string exceeded [PATH_MAX[. 
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11530 Also note that most of the errors are optional. If one of the variables always has the same value 

11531 on an implementation, the implementation need not look at path or fildes to return that value and 

11532 is, therefore, not required to detect any of the errors except the meaning of [EINVAL] that 

11533 indicates that the value of name is not valid for that variable. 

11534 If the value of any of the limits are indeterminate (logically infinite), they are defined in 

11535 <limits.h> and the pathconf() and fpathconf () functions return-1 without changing errno. This 

11536 can be distinguished from the case of giving an unrecognized name argument because errno is set 

11537 to [EINVAL] in this case. 

11538 Since -1 is a valid return value for the pathconf( ) and fpathconf () functions, applications should 

11539 set errno to zero before calling them and check errno only if the return value is -1. I 

11540 For the case of {SYMLINK_MAX}, since both pathconf( ) and open() follow symbolic links, there I 

11541 is no way that path or fildes could refer to a symbolic link. I 

11542 FUTURE DIRECTIONS 

11543 None. 

11544 SEE ALSO 

11545 confstr (), sysconf( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <limits.h>, 

11546 <unistd.h>, the Commands and Utilities volume of IEEE Std. 1003.1-200x 

11547 CHANGE HISTORY 

11548 First released in Issue 3. 

11549 Entry included for alignment with the POSIX.1-1988 standard. 

11550 Issue 4 

11551 Th e fpathconf ( ) function now has the full long int return type in the SYNOPSIS section. 

11552 The following changes gave been made for alignment with the ISO POSIX-1 standard: 

11553 • The type of argument path is changed from char* to const char*. Also, the return value of 

11554 both functions is changed from long to long int. 

11555 • In the DESCRIPTION, the words "The behavior is undefined if" have been replaced by "it is 

11556 unspecified whether an implementation supports an association of the variable name with 

11557 the specified file" in notes 2,4, and 6. 

11558 • In the RETURN VALUE section, errors associated with the use of path and fildes, when an 

11559 implementation does not support the requested association, are now specified separately. 

11560 • The requirement that errno be set to indicate the error is added. 

11561 The following change is incorporated for alignment with the FIPS requirements: 

11562 • In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 

11563 name component is larger that jNAME_MAX} is now defined as mandatory and marked as 

11564 an extension. 

11565 Issue 4, Version 2 

11566 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 

11567 • It states that [ELOOP] is returned if too many symbolic links are encountered during path 

11568 name resolution. 

11569 • A second [ENAMETOOLONG] condition is defined that may report excessive length of an 

11570 intermediate result of path name resolution of a symbolic link. 
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11572 

11573 

11574 

11575 

11576 

11577 

11578 

11579 

11580 

11581 

11582 

11583 

11584 

11585 

11586 

11587 

11588 


Issue 5 

The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 
Large File Summit extensions are added. 


Issue 6 


The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 
This is since behavior may vary from one file system to another. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

. The DESCRIPTION is updated to include {FILESIZEBITS}. 

• The [ELOOP] mandatory error condition is added. 

• A second [ENAMETOOLONG] is added as an optional error condition. 

The following changes were made to align with the IEEE P1003.1a draft standard: 


. The _PC_SYMLINK_MAX entry is added to the table in the DESCRIPTION. 


The pathconfO variables iPOSIX_ALLOC_SIZE_MIN), 

{POSIX_REC_M AX_XFER_SIZE [, 

|POSIX_REC_XFER_ALIGN) and their associated names 
IEEE Std. 1003.1d-1999. 


{POSIX_REC_IN C R_XFER_SIZE}, 
jPOSIX_REC_MIN_XFER_SIZE}, 
are added for alignment with 
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11589 NAME 

11590 fprintf, printf, snprintf, sprintf — print formatted output 

11591 SYNOPSIS 

11592 #include <stdio.h> 

11593 int fprintf (FILE * stream, const char * format , . . . ) ; 

11594 int printf (const char * format, . . . ) ; 

11595 xsi int snprintf (char *s, size_t n, const char * format, ...); 

11596 int sprintf (char *s, const char * format, ...); 

11597 DESCRIPTION 

11598 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

11599 conflict between the requirements described here and the ISO C standard is unintentional. This I 

11600 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

11601 Th e fprintf () function places output on the named output stream. The printf() function places 

11602 output on the standard output stream stdout. The sprintf() function places output followed by 

11603 the null byte, ' \ 0', in consecutive bytes starting at *s; it is the user's responsibility to ensure that 

11604 enough space is available. 

11605 xsi The snprintf () function is identical to sprintf () with the addition of the n argument, which states 

11606 the size of the buffer referred to by s. If n is greater than zero, but not large enough to hold all 

11607 output bytes specified by the format, output bytes beyond the n- 1st are discarded rather than 

11608 being written into the array. 

11609 If copying takes place between objects that overlap as a result of a call to sprintf () or snprintf (), 

11610 the results are undefined. 

11611 Each of these functions converts, formats, and prints its arguments under control of the format. 

11612 The format is a character string, beginning and ending in its initial shift state, if any. The format is 

11613 composed of zero or more directives: ordinary characters, which are simply copied to the output 

11614 stream, and conversion specifications, each of which results in the fetching of zero or more 

11615 arguments. The results are undefined if there are insufficient arguments for the format. If the 

11616 format is exhausted while arguments remain, the excess arguments are evaluated but are 

11617 otherwise ignored. 

11618 xsi Conversions can be applied to the nth argument after the format in the argument list, rather than 

11619 to the next unused argument. In this case, the conversion character ' %' (see below) is replaced 

11620 by the sequence " %n$", where n is a decimal integer in the range [1,{NL_ARGMAX}], giving the 

11621 position of the argument in the argument list. This feature provides for the definition of format 

11622 strings that select arguments in an order appropriate to specific languages (see the EXAMPLES 

11623 section). 

11624 In format strings containing the " %n$" form of conversion specifications, numbered arguments 

11625 in the argument list can be referenced from the format string as many times as required. 

11626 In format strings containing the ' %' form of conversion specifications, each argument in the 

11627 argument list is used exactly once. 

11628 All forms of the fprintf () functions allow for the insertion of a language-dependent radix 

11629 character in the output string. The radix character is defined in the program's locale (category 

11630 LC_NUMERIC). In the POSIX locale, or in a locale where the radix character is not defined, the 

11631 radix character defaults to a period (' .'). 

11632 xsi Each conversion specification is introduced by the ' %' character or by the character sequence 

11633 " %n$ ",after which the following appear in sequence: 
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• Zero or more flags (in any order), which modify the meaning of the conversion specification. 

• An optional minimum field width . If the converted value has fewer bytes than the field 

width, it shall be padded with spaces by default on the left; it shall be padded on the right, if 
the left-adjustment flag described below, is given to the field width. The field width 

takes the form of an asterisk (' *'), described below, or a decimal integer. 

• An optional precision that gives the minimum number of digits to appear for the d, i, o, u, x, 
and X conversions; the number of digits to appear after the radix character for the e, E, and / 
conversions; the maximum number of significant digits for the g and G conversions; or the 

xsi maximum number of bytes to be printed from a string in s and S conversions. The precision 

takes the form of a period (' .') followed either by an asterisk (' *'), described below, or an 
optional decimal digit string, where a null digit string is treated as 0. If a precision appears 
with any other conversion character, the behavior is undefined. 

• An optional h specifying that a following d, i, o, u, x, or X conversion character applies to a 
type short int or type unsigned short int argument (the argument shall have been promoted 
according to the integral promotions, and its value shall be converted to type short int or 
unsigned short int before printing); an optional h specifying that a following n conversion 
character applies to a pointer to a type short int argument; an optional l (ell) specifying that a 
following d, i, o, it, x, or X conversion character applies to a type long int or unsigned long 
int argument; an optional l (ell) specifying that a following n conversion character applies to 
a pointer to a type long int argument; or an optional L specifying that a following e, E,f, g, or 

G conversion character applies to a type long double argument. An optional / (ell) specifying I 
that a following c conversion character applies to a wint_t argument; an optional l (ell) I 
specifying that a following s conversion character applies to a pointer to a wchar_t argument. I 
If an h, /, or L appears with any other conversion character, the behavior is undefined. I 

• A conversion character that indicates the type of conversion to be applied. 

A field width, or precision, or both, may be indicated by an asterisk ('*'). In this case an 
argument of type int supplies the field width or precision. Applications shall ensure that I 
arguments specifying field width, or precision, or both appear in that order before the argument, I 
if any, to be converted. A negative field width is taken as a ' - ' flag followed by a positive field I 
xsi width. A negative precision is taken as if the precision were omitted. In format strings 
containing the "%n$" form of a conversion specification, a field width or precision may be 
indicated by the sequence " *m$", where m is a decimal integer in the range [1,|NL_ARGMAX}] 
giving the position in the argument list (after the format argument) of an integer argument 
containing the field width or precision, for example: 

printf("%l$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec); 

The format can contain either numbered argument specifications (that is, "%n$ " and " *m$ "), or 
unnumbered argument specifications (that is, ' %' and ' *'), but normally not both. The only 
exception to this is that "%%" can be mixed with the "%n$" form. The results of mixing 
numbered and unnumbered argument specifications in a format string are undefined. When 
numbered argument specifications are used, specifying the Nth argument requires that all the 
leading arguments, from the first to the (N-l)th, are specified in the format string. 

The flag characters and their meanings are: 

xsi ' The integer portion of the result of a decimal conversion (%z, %d, %», %/, °/,g, or %G) 

shall be formatted with thousands' grouping characters. For other conversions the 
behavior is undefined. The non-monetary grouping character is used. 

- The result of the conversion shall be left-justified within the field. The conversion is 

right-justified if this flag is not specified. 
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+ The result of a signed conversion shall always begin with a sign ('+' or The 

conversion shall begin with a sign only when a negative value is converted if this flag is 
not specified. 

<space> If the first character of a signed conversion is not a sign or if a signed conversion results 
in no characters, a space shall be prefixed to the result. This means that if the space and 
' +' flags both appear, the space flag shall be ignored. 

# This flag specifies that the value is to be converted to an alternative form. For o 

conversion, it increases the precision (if necessary) to force the first digit of the result to 
be 0. For x or X conversions, a non-zero result shall have Ox (or OX) prefixed to it. For e, 
E, f, g, or G conversions, the result shall always contain a radix character, even if no 
digits follow the radix character. Without this flag, a radix character appears in the 
result of these conversions only if a digit follows it. For g and G conversions, trailing 
zeros shall not be removed from the result as they normally are. For other conversions, 
the behavior is undefined. 

0 For d, i, o, u, x, X, e, E,f, g, and G conversions, leading zeros (following any indication of 

sign or base) are used to pad to the field width; no space padding is performed. If the 0 
and ' flags both appear, the 0 flag is ignored. For d, i, o, n, x, and X conversions, if a 
precision is specified, the 0 flag is ignored. If the 0 and ' ' ' flags both appear, the 
grouping characters are inserted before zero padding. For other conversions, the 
behavior is undefined. 

The conversion characters and their meanings are: 

d, i The int argument is converted to a signed decimal in the style [-\dddd. The precision 
specifies the minimum number of digits to appear; if the value being converted can be 
represented in fewer digits, it shall be expanded with leading zeros. The default 
precision is 1. The result of converting 0 with an explicit precision of 0 is no characters. 

o The unsigned int argument is converted to unsigned octal format in the style dddd. The 

precision specifies the minimum number of digits to appear; if the value being 
converted can be represented in fewer digits, it shall be expanded with leading zeros. 
The default precision is 1. The result of converting 0 with an explicit precision of 0 is no 
characters. 

u The unsigned int argument is converted to unsigned decimal format in the style dddd. 

The precision specifies the minimum number of digits to appear; if the value being 
converted can be represented in fewer digits, it shall be expanded with leading zeros. 
The default precision is 1. The result of converting 0 with an explicit precision of 0 is no 
characters. 

x The unsigned int argument is converted to unsigned hexadecimal format in the style 

dddd; the letters " abodef" are used. The precision specifies the minimum number of 
digits to appear; if the value being converted can be represented in fewer digits, it shall 
be expanded with leading zeros. The default precision is 1. The result of converting 0 
with an explicit precision of 0 is no characters. 

X Behaves the same as the x conversion character except that letters " ABCDEF" are used 

instead of " abodef". 

/ The double argument is converted to decimal notation in the style [~]ddd.ddd, where 

the number of digits after the radix character is equal to the precision specification. If 
the precision is missing, it is taken as 6; if the precision is explicitly 0 and no ' #' flag is 
present, no radix character appears. If a radix character appears, at least one digit 
appears before it. The value is rounded to the appropriate number of digits. 
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xsi Th e fprintf() family of functions may make available character string representations 

for infinity and NaN. 

e, £ The double argument is converted in the style [~]d.ddde±dd, where there is one digit 
before the radix character (which is non-zero if the argument is non-zero) and the 
number of digits after it is equal to the precision; if the precision is missing, it is taken 
as 6; if the precision is 0 and no ' #' flag is present, no radix character appears. The 
value is rounded to the appropriate number of digits. The E conversion character will 
produce a number with £ instead of e introducing the exponent. The exponent always 
contains at least two digits. If the value is 0, the exponent is 0. 

xsi The fprintf () family of functions may make available character string representations 

for infinity and NaN. 

g, G The double argument is converted in the style/or e (or in the style £ in the case of a G 
conversion character), with the precision specifying the number of significant digits. If 
an explicit precision is 0, it is taken as 1. The style used depends on the value 
converted; style e (or E) shall be used only if the exponent resulting from such a 
conversion is less than -4 or greater than or equal to the precision. Trailing zeros are 
removed from the fractional portion of the result; a radix character appears only if it is 
followed by a digit. 

xsi The fprintf () family of functions may make available character string representations 

for infinity and NaN. 

c The int argument is converted to an unsigned char, and the resulting byte is written. 

If an / (ell) qualifier is present, the wint_t argument is converted as if by an Is 
conversion specification with no precision and an argument that points to a two- 
element array of type wchar_t, the first element of which contains the wint_t argument 
to the Is conversion specification and the second element contains a null wide 
character. 

s The argument shall be a pointer to an array of char. Bytes from the array are written up I 

to (but not including) any terminating null byte. If the precision is specified, no more 
than that many bytes shall be written. If the precision is not specified or is greater than I 
the size of the array, the application shall ensure that the array contains a null byte. I 

If an l (ell) qualifier is present, the argument shall be a pointer to an array of type I 
wchar_t. Wide characters from the array are converted to characters (each as if by a 
call to the ivcrtomb () function, with the conversion state described by an mbstate_t 
object initialized to zero before the first wide character is converted) up to and 
including a terminating null wide character. The resulting characters shall be written 
up to (but not including) the terminating null character (byte). If no precision is 
specified, the application shall ensure that the array contains a null wide character. If a I 
precision is specified, no more than that many characters (bytes) shall be written I 
(including shift sequences, if any), and the array shall contain a null wide character if, I 
to equal the character sequence length given by the precision, the function would need I 
to access a wide character one past the end of the array. In no case is a partial character I 
written. I 

p The argument shall be a pointer to void. The value of the pointer is converted to a I 

sequence of printable characters, in an implementation-dependent manner. 

n The argument shall be a pointer to an integer into which is written the number of bytes I 

written to the output so far by this call to one of th e fprintf ( ) functions. No argument is 
converted. 
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11775 xsi C Same as Ic. 

11776 xsi S Same as Is. 

11777 % Print a no argument is converted. The entire conversion specification shall be I 

11778 

11779 If a conversion specification does not match one of the above forms, the behavior is undefined. 

11780 In no case does a nonexistent or small field width cause truncation of a field; if the result of a 

11781 conversion is wider than the field width, the field is simply expanded to contain the conversion 

11782 result. Characters generated by fprintf () and printf( ) are printed as if fpntc() had been called. 

11783 cx The stjctime and s t_mtime fields of the file shall be marked for update between the call to a 

11784 successful execution of fprintf ( ) or printfi ) and the next successful completion of a call to /flush () 

11785 or fclose( ) on the same stream or a call to exit () or abort( ). 

11786 RETURN VALUE 

11787 Upon successful completion, the fprintf () and printf( ) functions shall return the number of bytes 

11788 transmitted. 

11789 Upon successful completion, the sprintf( ) function shall return the number of bytes written to s, 

11790 excluding the terminating null byte. 

11791 xsi Upon successful completion, the snprintf( ) function shall return the number of bytes that would 

11792 be written to s had n been sufficiently large excluding the terminating null byte. 

11793 If an output error was encountered, these functions shall return a negative value. 

11794 xsi If the value of n is zero on a call to snprintf( ), an unspecified value shall be returned. 

11795 ERRORS 

11796 For the conditions under which fprintf () and printf() fail and may fail, refer to fpntc() or 

11797 fputivc{). 

11798 In addition, all forms of fprintf () may fail if: 

11799 xsi [EILSEQ] A wide-character code that does not correspond to a valid character has been 

11800 detected. 

11801 xsi [EINVAL] There are insufficient arguments. 

11802 The printf( ) and fprintf () functions may fail if: 

11803 xsi [ENOMEM] Insufficient storage space is available. 

11804 The snprintf( ) function shall fail if: 

11805 xsi [EOVERFLOW] The value of n is greater than |INT_MAX} or the number of bytes needed to 

11806 hold the output excluding the terminating null is greater than |INT_MAX}. 

11807 EXAMPLES 

11808 Printing Language-Independent Date and Time 

11809 The following statement can be used to print date and time using a language-independent 

11810 format: 

11811 printf (format, weekday, month, day, hour, min); 

11812 For American usage, format could be a pointer to the following string: 

11813 "%s, %s %d, %d:%.2d\n" 
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This example would produce the following message: 

Sunday, July 3, 10:02 

For German usage, format could be a pointer to the following string: 

"%l$s, %3$d. %2$s, %4$d:%5$.2d\n" 

This definition of format would produce the following message: 

Sonntag, 3. Juli, 10:02 

Printing File Information 

The following example prints information about the type, permissions, and number of links of a 
specific file in a directory. 

The first two calls to printf() use data decoded from a previous stat () call. The user-defined 
strperm () function shall return a string similar to the one at the beginning of the output for the 
following command: 

Is -1 

The next call to printf () outputs the owner's name if it is found using getpivnid (); the getpzvnid() 
function shall return a passwd structure from which the name of the user is extracted. If the user 
name is not found, the program instead prints out the numeric value of the user ID. 

The next call prints out the group name if it is found using getgrgid (); getgrgid () is very similar to 
getpivuid() except that it shall return group information based on the group number. Once 
again, if the group is not found, the program prints the numeric value of the group for the entry. 

The final call to printf () prints the size of the file. 

#include <stdio.h> 

#include <sys/types.h> 

#include <pwd.h> 

#include <grp.h> 

char *strperm (mode_t); 

struct stat statbuf; 
struct passwd *pwd; 
struct group *grp; 

printf ("%10.10s", strperm (statbuf.st_mode)); 
printf ("%4d", statbuf.st_nlink); 

if ((pwd = getpwuid (statbuf.st_uid)) != NULL) 

printf (" %-8.8s", pwd->pw_name); 

else 

printf (" %-8d", statbuf.st_uid); 

if ((grp = getgrgid (statbuf.st_gid)) != NULL) 

printf (" %-8.8s", grp->gr_name); 

else 

printf (" %-8d", statbuf.st_gid); 
printf ("%91d", statbuf.st_size); 
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Printing a Localized Date String 

The following example gets a localized date string. The nl_langinfo () function shall return the 
localized date string, which specifies the order and layout of the date. The strftimei ) function 
takes this information and, using the tm structure for values, places the date and time 
information into datestring. The printfi ) function then outputs datestring and the name of the 
entry. 

#include <stdio.h> 

#include <time.h> 

#include <langinfo.h> 

struct dirent *dp; 

struct tm *tm; 

char datestring[256] ; 

strftime (datestring, sizeof (datestring) , nl_langinfo (D_T_FMT) , tm) ; 
printf (" %s %s\n", datestring, dp->d_name); 


Printing Error Information 

The following example uses fprintf ( ) to write error information to stadard error. 

In the first group of calls, the program tries to open the password lock file named LOCKFILE. If 
the file already exists, this is an error, as indicated by the 0_EXCL flag on the open () function. If 
the call fails, the program assumes that someone else is updating the password file, and the 
program exits. 

The next group of calls saves a new password file as the current password file by creating a link 
between LOCKFILE and the new password file PASSWDFILE. 

#include <sys/types.h> 

#include <sys/stat.h> 

#include <fcntl.h> 

#include <stdio.h> 

#include <stdlib.h> 

#include <unistd.h> 

#include <string.h> 

#include <errno.h> 

#define LOCKFILE "/etc/ptmp" 
tdefine PASSWDFILE "/etc/passwd" 

int pfd; 

if ((pfd = open (LOCKFILE, 0_WRONLY | 0_CREAT | 0_EXCL, 

S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH)) == -1) 

{ 

fprintf (stderr, "Cannot open /etc/ptmp. Try again later.\n"); 
exit (1); 

} 


if (link (LOCKFILE,PASSWDFILE) == -1) { 

fprintf (stderr, "Link error: %s\n", strerror (errno)) ; 
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exit (1); 

} 


Printing Usage Information 

The following example checks to make sure the program has the necessary arguments, and uses 
fprintf () to print usage information if the expected number of arguments is not present. 

#include <stdio.h> 

#include <stdlib.h> 

char *Options = "hdbtl"; 

if (argc < 2) { 

fprintf (stderr, "Usage: %s -%s <file\n", argv[0]. Options); exit (1) 

} 


Formatting a Decimal String 

The following example prints a key and data pair on stdont. Note use of the ' *' (asterisk) in the 
format string; this ensures the correct number of decimal places for the element based on the 
number of elements requested. 

#include <stdio.h> 

long i; 

char *keystr; 

int elementlen, len; 

while (len < elementlen) { 

printf ("%s Element%0*ld\n", keystr, elementlen, i); 

} 


Creating a File Name 

The following example creates a file name using information from a previous getpivnam () 
function that returned the HOME directory of the user. 

#include <stdio.h> 

#include <sys/types.h> 

#include <unistd.h> 

char filename[PATH_MAX+1] ; 
struct passwd *pw; 

sprintf (filename, "%s/%d.out", pw->pw_dir, getpidO); 
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Reporting an Event 

The following example loops until an event has timed out. The panse () function waits forever 
unless it receives a signal. The fprintf () statement should never occur due to the possible return 
values of pause{). 

#include <stdio.h> 

#include <unistd.h> 

#include <string.h> 

#include <errno.h> 

while (!event_complete) { 

if (pause() != -1 || errno != EINTR) 

fprintf (stderr, "pause: unknown error: %s\n", strerror (errno)) 

} 


Printing Monetary Information 

The following example uses strfmon () to convert a number and store it as a formatted monetary 
string named convbuf. If the first number is printed, the program prints the format and the 
description; otherwise, it just prints the number. 

#include <monetary.h> 

#include <stdio.h> 

struct tblfmt { 
char *format; 
char *description; 

}; 


struct tblfmt tablet] = { 

{ "%n", "default formatting" }, 

{ "%lln", "right align within an 11 character field" }, 

{ "%#5n", "aligned columns for values up to 99,999" }, 

{ "%=*#5n", "specify a fill character" }, 

{ "%=0#5n", "fill characters do not use grouping" }, 

{ "%~#5n", "disable the grouping separator" }, 

{ "%~#5.0n", "round off to whole units" }, 

{ "%~#5.4n", "increase the precision" }, 

{ "%(#5n", "use an alternative pos/neg style" }, 

{ "%!(#5n", "disable the currency symbol" }, 


float input[3]; 
int i, j; 

char convbuf[100]; 

strfmon (convbuf, sizeof (convbuf), table[i].format, input [j]); 
if (j == 0) { 

printf ("%s%s%s\n", table[i].format, 
convbuf, table[i].description); 

} 
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else { 

printf ("%s\n", convbuf); 

} 


APPLICATION USAGE 

If the application calling fprintf () has any objects of type wint_t or wchar_t, it must also include 
the <wchar.h> header to have these objects defined. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

fpntc(), fscanf(), setlocale(), wcrtomb(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <stdio.h>, <wchar.h>, the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Chapter 7, Locale I 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

In the DESCRIPTION, references to langinfo data are marked as extensions. The reference to 
langinfo data is removed from the description of the radix character. 

The ' ' ' (single-quote) flag is added to the list of flag characters and marked as an extension. 
This flag directs that numeric conversion is formatted with the decimal grouping character. 

The detailed description of these functions is provided here instead of under printf ’(). 

The information in the APPLICATION USAGE section is moved to the DESCRIPTION. A new 
APPLICATION USAGE section is added. 

The [EILSEQ] error is added to the ERRORS section and all errors are marked as extensions. 

The following changes are incorporated for alignment with the ISO C standard: 

• The type of the format arguments is changed from char’'' to const char*. 

• The DESCRIPTION is reworded or presented differently in a number of places for alignment 
with the ISO C standard, and also for clarity. There are no functional changes, except as 
noted elsewhere in this CHANGE HISTORY section. 

The following changes are incorporated for alignment with the MSE working draft: 

• The C and S conversion characters are added, indicating respectively a wide character of type 
wchar_t and pointer to a wide-character string of type wchar_t* in the argument list. 

Issue 4, Version 2 

The [ENOMEM] error is added to the ERRORS section as an optional error. 

Issue 5 

Aligned with ISO/IEC 9899:1990/Amendment 1:1995 (E). Specifically, the l (ell) qualifier can 
now be used with c and s conversion characters. 

The snprintf () function is new in Issue 5. 
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Issue 6 

Extensions beyond the ISO C standard are now marked. 

The description of snprintf () has been aligned with The Open Group Base Resolution bwg98-006. I 
This aligns snprintfi ) with historic BSD behavior. I 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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12039 NAME 

12040 fputc — put a byte on a stream 

12041 SYNOPSIS 

12042 #include <stdio.h> 

12043 int fputc (int c, FILE * stream); 

12044 DESCRIPTION 

12045 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

12046 conflict between the requirements described here and the ISO C standard is unintentional. This I 

12047 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

12048 The fputc () function shall write the byte specified by c (converted to an unsigned char) to the 

12049 output stream pointed to by stream, at the position indicated by the associated file-position 

12050 indicator for the stream (if defined), and advances the indicator appropriately. If the file cannot 

12051 support positioning requests, or if the stream was opened with append mode, the byte shall be 

12052 appended to the output stream. 

12053 cx The stjctime and stjntime fields of the file shall be marked for update between the successful 

12054 execution of fputc () and the next successful completion of a call to /flush () or /close () on the same 

12055 stream or a call to exit () or abort (). 

12056 RETURN VALUE 

12057 Upon successful completion, fputc () shall return the value it has written. Otherwise, it shall 

12058 cx return EOF, the error indicator for the stream shall be set, and errno shall be set to indicate the 

12059 error. 

12060 ERRORS 

12061 The fputc () function shall fail if either the stream is unbuffered or the stream's buffer needs to be 

12062 flushed, and: 

12063 cx [EAGAIN] The 0_NONBLOCK flag is set for the file descriptor underlying stream and the 

12064 process would be delayed in the write operation. 

12065 cx [EBADF] The file descriptor underlying stream is not a valid file descriptor open for 

12066 writing. 

12067 cx [EFBIG] An attempt was made to write to a file that exceeds the maximum file size. 

12068 xsi [EFBIG] An attempt was made to write to a file that exceeds the process' file size limit. 

12069 man [EFBIG] The file is a regular file and an attempt was made to write at or beyond the 

12070 offset maximum. 

12071 cx [EINTR] The write operation was terminated due to the receipt of a signal, and no data 

12072 was transferred. 

12073 cx [EIO] A physical I/O error has occurred, or the process is a member of a 

12074 background process group attempting to write to its controlling terminal, 

12075 TOSTOP is set, the process is neither ignoring nor blocking SIGTTOU, and the 

12076 process group of the process is orphaned. This error may also be returned 

12077 under implementation-dependent conditions. 

12078 cx [ENOSPC] There was no free space remaining on the device containing the file. 

12079 cx [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by 

12080 any process. A SIGPIPE signal shall also be sent to the thread. 

12081 The fputc () function may fail if: 
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12116 
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12118 

12119 
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12121 


man [ENOMEM] Insufficient storage space is available. 

man [ENXIO] A request was made of a nonexistent device, or the request was outside the 

capabilities of the device. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

/ error (), /open (), getrlimit(), pntc{), pnts(), setbuf(), ulimit(), the System Interface Definitions 
volume of IEEE Std. 1003.1-200x, <stdio.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

In the DESCRIPTION, the text is changed to make it clear that the function writes byte values, 
rather than (possibly multi-byte) character values. 

In the ERRORS section, text is added to indicate that error returns are only generated when 
either the stream is unbuffered, or if the stream buffer needs to be flushed. 

Also in the ERRORS section, in previous issues 
whether or not an implementation supported Job 
mandatory. 

The [ENXIO] error is moved to the list of optional 
as extensions. 

The description of [EINTR] is amended. 

The [EFBIG] error is marked to show extensions. 

Issue 4, Version 2 

In the ERRORS section, the description of [EIO] is 
I/O error occurs. 

Issue 5 

Large File Summit extensions are added. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The [EIO] and [EFBIG] mandatory error conditions are added. 

• The [ENOMEM] and [ENXIO] optional error conditions are added. 


generation of the [EIO] error depended on 
Control. This functionality is now defined as 

errors, and all the optional errors are marked 

updated to include the case where a physical 
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12122 NAME 

12123 fputs — put a string on a stream 

12124 SYNOPSIS 

12125 tinclude <stdio.h> 

12126 int fputs (const char *s, FILE * stream) ; 

12127 DESCRIPTION 

12128 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

12129 conflict between the requirements described here and the ISO C standard is unintentional. This I 

12130 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

12131 The/p»fs() function shall write the null-terminated string pointed to by s to the stream pointed 

12132 to by stream . The terminating null byte shall not be written. 

12133 cx The stjctime and stjntime fields of the file shall be marked for update between the successful 

12134 execution of fputs () and the next successful completion of a call to /flush () or /close ( ) on the same 

12135 stream or a call to exit () or abort (). 

12136 RETURN VALUE 

12137 Upon successful completion, fputs() shall return a non-negative number. Otherwise, it shall 

12138 cx return EOF, set an error indicator for the stream, and set errno to indicate the error. 

12139 ERRORS 

12140 Refer to fpntc(). 

12141 EXAMPLES 

12142 Printing to Standard Output 

12143 The following example gets the current time, converts it to a string using localtime () and 

12144 asctime( ), and prints it to standard output using fputs (). It then prints the number of minutes to 

12145 an event for which it is waiting. 

12146 #include <time.h> 

12147 #include <stdio.h> 

12148 

12149 time_t now; 

12150 int minutes_to_event; 

12151 

12152 time (Snow) ; 

12153 printf ("The time is "); 

12154 fputs (asctime (localtime (Snow) ) , stdout); 

12155 printf ("There are still %d minutes to the event.\n", 

12156 minutes_to_event) ; 

12157 

12158 APPLICATION USAGE 

12159 The pnts( ) function appends a <newline> character while fputs () does not. 

12160 RATIONALE 

12161 None. 

12162 FUTURE DIRECTIONS 

12163 None. 
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12164 SEE ALSO 

12165 fopen(), pntc(), pnts{), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

12166 <stdio.h> 

12167 CHANGE HISTORY 

12168 First released in Issue 1. 

12169 Derived from Issue 1 of the SVID. 

12170 Issue 4 

12171 In the DESCRIPTION, the words "null character" are replaced by "null byte", to make it clear 

12172 that this function deals solely in byte values. 

12173 The following change is incorporated for alignment with the ISO C standard: 

12174 • The type of argument s is changed from char’'' to const char*. 

12175 Issue 6 

12176 Extensions beyond the ISO C standard are now marked. 
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12177 NAME 

12178 fputwc — put a wide-character code on a stream 

12179 SYNOPSIS 

12180 tinclude <stdio.h> 

12181 tinclude <wchar.h> 


12182 wint_t fputwc (wchar_t wc, FILE * stream); 

12183 DESCRIPTION 

12184 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

12185 conflict between the requirements described here and the ISO C standard is unintentional. This I 

12186 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

12187 The fpntzvc() function shall write the character corresponding to the wide-character code zvc to 

12188 the output stream pointed to by stream, at the position indicated by the associated file-position 

12189 indicator for the stream (if defined), and advances the indicator appropriately. If the file cannot 

12190 support positioning requests, or if the stream was opened with append mode, the character is 

12191 appended to the output stream. If an error occurs whilst writing the character, the shift state of 

12192 the output file is left in an undefined state. 

12193 cx The st_ctime and stjntime fields of the file shall be marked for update between the successful 

12194 execution oi fpntivc() and the next successful completion of a call to /flush () or /close () on the 

12195 same stream or a call to exit () or abort (). 

12196 RETURN VALUE 

12197 Upon successful completion, fputzvc( ) shall return zvc. Otherwise, it shall return WEOF, the error 

12198 cx indicator for the stream shall be set set, and errno shall be set to indicate the error. 

12199 ERRORS 

12200 The fputzvc( ) function shall fail if either the stream is unbuffered or data in the stream's buffer 

12201 needs to be written, and: 

12202 cx [EAGAIN] The 0_NONBLOCK flag is set for the file descriptor underlying stream and the 

12203 process would be delayed in the write operation. 

12204 cx [EBADF] The file descriptor underlying stream is not a valid file descriptor open for 

12205 writing. 

12206 cx [EFBIG] An attempt was made to write to a file that exceeds the maximum file size or 

12207 the process' file size limit. 

12208 man [EFBIG] The file is a regular file and an attempt was made to write at or beyond the 

12209 offset maximum associated with the corresponding stream. 

12210 cx [EINTR] The write operation was terminated due to the receipt of a signal, and no data 

12211 was transferred. 

12212 cx [EIO] A physical I/O error has occurred, or the process is a member of a 

12213 background process group attempting to write to its controlling terminal, 

12214 TOSTOP is set, the process is neither ignoring nor blocking SIGTTOU, and the 

12215 process group of the process is orphaned. This error may also be returned 

12216 under implementation-dependent conditions. 

12217 cx [ENOSPC] There was no free space remaining on the device containing the file. 

12218 cx [EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by 

12219 any process. A SIGPIPE signal shall also be sent to the thread. 
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12220 Th efputzvc () function may fail if: 

12221 cx [ENOMEM] Insufficient storage space is available. 

12222 cx [ENXIO] A request was made of a nonexistent device, or the request was outside the 

12223 capabilities of the device. 

12224 cx [EILSEQ] The wide-character code zvc does not correspond to a valid character. 

12225 EXAMPLES 

12226 None. 

12227 APPLICATION USAGE 

12228 None. 

12229 RATIONALE 

12230 None. 

12231 FUTURE DIRECTIONS 

12232 None. 

12233 SEE ALSO 

12234 /error (), fopen(), setbufi ), ulimit(), the System Interface Definitions volume of 

12235 IEEE Std. 1003.1-200x, <stdio.h>, <wchar.h> 

12236 CHANGE HISTORY 

12237 First released in Issue 4. 

12238 Derived from the MSE working draft. 

12239 Issue 4, Version 2 

12240 In the ERRORS section, the description of [EIO] is updated to include the case where a physical 

12241 I/O error occurs. 

12242 Issue 5 

12243 Aligned with ISO/IEC 9899:1990/Amendment 1:1995 (E). Specifically, the type of argument zvc 

12244 is changed from wint_t to wchar_t 

12245 The Optional Header (OH) marking is removed from <stdio.h>. 

12246 Large File Summit extensions are added. 

12247 Issue 6 

12248 Extensions beyond the ISO C standard are now marked. 

12249 The following new requirements on POSIX implementations derive from alignment with the 

12250 Single UNIX Specification: 

12251 • The [EFBIG] and [EIO] mandatory error conditions are added. 
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12252 NAME 

12253 fputws — put a wide-character string on a stream 

12254 SYNOPSIS 

12255 tinclude <stdio.h> 

12256 tinclude <wchar.h> 

12257 int fputws (const wchar_t *ws, FILE * stream) ; 

12258 DESCRIPTION 

12259 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

12260 conflict between the requirements described here and the ISO C standard is unintentional. This I 

12261 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

12262 The fpntivs() function shall write a character string corresponding to the (null-terminated) 

12263 wide-character string pointed to by zvs to the stream pointed to by stream. No character 

12264 corresponding to the terminating null wide-character code shall be written. 

12265 cx The st_ctime and st_mtime fields of the file shall be marked for update between the successful 

12266 execution oifputws() and the next successful completion of a call to /flush () or /close () on the 

12267 same stream or a call to exit () or abort (). 

12268 RETURN VALUE 

12269 Upon successful completion , fputws() shall return a non-negative number. Otherwise, it shall 

12270 cx return -1, set an error indicator for the stream, and set errno to indicate the error. 

12271 ERRORS 

12272 Refer to fpntzvc (). 

12273 EXAMPLES 

12274 None. 

12275 APPLICATION USAGE 

12276 Th e fputws () function does not append a <newline> character. 

12277 RATIONALE 

12278 None. 

12279 FUTURE DIRECTIONS 

12280 None. 

12281 SEE ALSO 

12282 fopen (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdio.h>, <wchar.h> 

12283 CHANGE HISTORY 

12284 First released in Issue 4. 

12285 Derived from the MSE working draft. 

12286 Issue 5 

12287 The Optional Header (OH) marking is removed from <stdio.h>. 

12288 Issue 6 

12289 Extensions beyond the ISO C standard are now marked. 
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NAME 

fread — binary input 

SYNOPSIS 

#include <stdio.h> 

size_t fread(void *ptr, size_t size, size_t nitems, FILE * stream); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The fread () function shall read into the array pointed to by ptr up to nitems members whose size 
is specified by size in bytes, from the stream pointed to by stream. The file position indicator for 
the stream (if defined) is advanced by the number of bytes successfully read. If an error occurs, 
the resulting value of the file position indicator for the stream is indeterminate. If a partial 
member is read, its value is indeterminate. 

cx Th e fread () function may mark the st_atime field of the file associated with stream for update. The 

st_atime field shall be marked for update by the first successful execution of fgetc(), fgets(), 
fgetwc(), fgetws(), fread(), fscanf(), getc(), getchar(), gets (), or scanf() using stream that returns 
data not supplied by a prior call to ungetc( ) or ungetwc (). 

RETURN VALUE 

Upon successful completion, fread () shall return the number of members successfully read 
which is less than nitems only if a read error or end-of-file is encountered. If size or nitems is 0, 
fread () shall return 0 and the contents of the array and the state of the stream remain unchanged, 
cx Otherwise, if a read error occurs, the error indicator for the stream shall be set, and errno shall be 

set to indicate the error. 

ERRORS 

Refer to fgetc{). 

EXAMPLES 

Reading from a Stream 

The following example reads a single element from the fp stream into the array pointed to by buf. 

#include <stdio.h> 

size_t bytes_read; 
char buf[100] ; 

FILE *fp; 

bytes_read = fread (buf, sizeof(buf), t, fp); 


APPLICATION USAGE 

The /error () or feoff) functions must be used to distinguish between an error condition and an 
end-of-file condition. 

Because of possible differences in member length and byte ordering, files written using /write () 
are application-dependent, and possibly cannot be read using fread () by a different application 
or by the same application on a different processor. 
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12333 RATIONALE 

12334 None. 

12335 FUTURE DIRECTIONS 

12336 None. 

12337 SEE ALSO 

12338 feof {), /error{ ), fopen(), getc(), gets(), scanf( ), the System Interface Definitions volume of 

12339 IEEE Std. 1003.1-200x, <stdio.h> 

12340 CHANGE HISTORY 

12341 First released in Issue 1. 

12342 Derived from Issue 1 of the SVID. 

12343 Issue 4 

12344 The list of functions that may cause the st_atime field to be updated is revised. 

12345 The following change is incorporated for alignment with the ISO C standard: 

12346 • In the RETURN VALUE section, the behavior if size or nitems is 0 is defined. 

12347 Issue 6 

12348 Extensions beyond the ISO C standard are now marked. 
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NAME 

free — free allocated memory 

SYNOPSIS 

#include <stdlib.h> 
void free(void *ptr ); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The free{ ) function shall cause the space pointed to by ptr to be deallocated; that is, made 
available for further allocation. If ptr is a null pointer, no action shall occur. Otherwise, if the 
argument does not match a pointer earlier returned by the calloc(), malloc( ), or realloc( ) function, 
or if the space is deallocated by a call to free( ) or realloc(), the behavior is undefined. 

Any use of a pointer that refers to freed space shall cause undefined behavior. 

RETURN VALUE 

Th efree( ) function shall return no value. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

There is now no requirement for the implementation to support the inclusion of <malloc.h>. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

calloc(), malloc(), realloc ( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

<stdlib.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The APPLICATION USAGE section is changed to record that <malloc.h> need no longer be 
supported on XSI-conformant systems. 

The following change is incorporated for alignment with the ISO C standard: 

• The DESCRIPTION now states that the behavior is undefined if any use is made of a pointer 
that refers to freed space. This was implied but not stated explicitly in Issue 3. 

Issue 4, Version 2 

The DESCRIPTION is updated for X/OPEN UNIX conformance to indicate that the free() 
function can also be used to free memory allocated by valloc(). 
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12390 Issue 6 

12391 Reference to the valloc () function is removed. 


386 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


freeaddrinfo() 


12392 NAME 

12393 freeaddrinfo, getaddrinfo — get address information 

12394 SYNOPSIS 

12395 tinclude <sys/socket. h> 

12396 tinclude <netdb.h> 

12397 void freeaddrinfo (struct addrinfo *ai); 

12398 int getaddrinfo (const char * nodename, const char * servname, 

12399 const struct addrinfo *hints, struct addrinfo **res) ; 

12400 DESCRIPTION 

12401 The freeaddrinfo () function frees one or more addrinfo structures returned by getaddrinfo (), along 

12402 with any additional storage associated with those structures. If the ai_next field of the structure 

12403 is not null, the entire list of structures is freed. The freeaddrinfo () function shall support the 

12404 freeing of arbitrary sublists of an addrinfo list originally returned by getaddrinfo (). 

12405 The getaddrinfo () function shall translate the name of a service location (for example, a host 

12406 name) and/or a service name and shall return a set of socket addresses and associated 

12407 information to be used in creating a socket with which to address the specified service. 

12408 The freeaddrinfo () and getaddrinfo () functions shall be thread-safe. 

12409 The nodename and servname arguments are either null pointers or pointers to null-terminated 

12410 strings. One or both of these two arguments shall be supplied by the application as a non-null 

12411 pointer. 

12412 The format of a valid name depends on the protocol family or families. If a specific family is not 

12413 given and the name could be interpreted as valid within multiple supported families, the 

12414 implementation shall attempt to resolve the name in all supported families and, in absence of 

12415 errors, one or more successful results shall be returned 

12416 If the nodename argument is not null, it can be a descriptive name or can be an address string. If 

12417 iP6 the specified address family is AF_INET, AF_INET6, or AF_UNSPEC, valid descriptive names 

12418 include host names. If the specified address family is AF_INET or AF_UNSPEC, address strings 

12419 using Internet standard dot notation as specified in inet_addr( ) are valid. 

12420 iP6 If the specified address family is AF_INET6 or AF_UNSPEC, standard IPv6 text forms described 

12421 in <REFERENCE UNDEFINED>(inet_pton) are valid. 

12422 If nodename is not null, the requested service location is named by nodename ; otherwise, the 

12423 requested service location is local to the caller. 

12424 If servname is null, the call shall return network-level addresses for the specified nodename. If 

12425 servname is not null, it is a null-terminated character string identifying the requested service. This 

12426 can be either a descriptive name or a numeric representation suitable for use with the address 

12427 iP6 family or families. If the specified address family is AF_INET, AF_INET6,or AF_UNSPEC, the 

12428 service can be specified as a string specifying a decimal port number. 

12429 If the hints argument is not null, it refers to a structure containing input values that may direct 

12430 the operation by providing options and by limiting the returned information to a specific socket 

12431 type, address family and/or protocol. In this hints structure every member other than ai_flags, 

12432 ai_famity, ai_socktype, and ai_protocol shall be set to zero or a null pointer. A value of 

12433 AF_UNSPEC for ai_family means that the caller shall accept any protocol family. A value of zero 

12434 for ai_socktype means that the caller shall accept any socket type. A value of zero for ai_protocol 

12435 means that the caller shall accept any protocol. If hints is a null pointer, the behavior shall be as if 

12436 it referred to a structure containing the value zero for the ai_flags, ai_socktype , and ai_protocol 

12437 fields, and AF_UNSPEC for the ai_family field. 
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Notes: 

1. If the caller handles only TCP and not UDP, for example, then the ai_protocol 
member of the hints structure should be set to IPPROTO_TCP when 
getaddrinfo () is called. 

2. If the caller handles only IPv4 and not IPv6, then the aijamily member of the 
hints structure should be set to PF_INET when getaddrinfo () is called. 

The ai_flags field to which the hints parameter points shall be set to zero or be the bitwise- 
inclusive OR of one or more of the values AI_PASSIVE, AI_CANONNAME, and 
AI_NUMERICHOST. 

If the AI_PASSIVE flag is specified, the returned address information shall be suitable for use in 
binding a socket for accepting incoming connections for the specified service. In this case, if the 
nodename argument is null, then the IP address portion of the socket address structure shall be 
set to INADDR_ANY for an IPv4 address or IN6ADDR_ANY_INIT for an IPv6 address. If the 
AI_PASSIVE flag is not specified, the returned address information shall be suitable for a call to 
connect( ) (for a connection-mode protocol) or for a call to connect (), sendto( ), or sendmsg( ) (for a 
connectionless protocol). In this case, if the nodename argument is null, then the IP address 
portion of the socket address structure shall be set to the loopback address. 

If the AI_CANONNAME flag is specified and the nodename argument is not null, the function 
attempts to determine the canonical name corresponding to nodename (for example, if nodename 
is an alias or shorthand notation for a complete name). 

If the AI_NUMERICHOST flag is specified, then a non-null nodename string supplied shall be a 
numeric host address string. Otherwise, an [EAI_NONAME] error is returned. This flag prevents 
any type of name resolution service (for example, the DNS) from being invoked. 

If the AI_NUMERICSERV flag is specified, then a non-null s ervname string supplied shall be a 
numeric port string. Otherwise, an [EAI_NONAME] error is returned. This flag prevents any 
type of name resolution service (for example, NIS+) from being invoked. 

The ai_socktype field to which argument hints points specifies the socket type for the service, as 
defined in socket (). If a specific socket type is not given (for example, a value of zero) and the 
service name could be interpreted as valid with multiple supported socket types, the 
implementation shall attempt to resolve the service name for all supported socket types and, in 
the absence of errors, all possible successful results shall be returned. A non-zero socket type 
value shall limit the returned information to values with the specified socket type. 

If the ai_family field to which hints points has the value AF_UNSPEC, addresses are returned for 
use with any protocol family that can be used with the specified nodename and/or servname. 
Otherwise, addresses are returned for use only with the specified protocol family. If ai_family is 
not AF_UNSPEC and ai_protocol is not zero, then addresses are returned for use only with the 
specified protocol family and protocol; the value of ai_protocol is interpreted as in a call to the 
socket () function with the corresponding values of ai_family and ai_protocol. 

RETURN VALUE 

A zero return value for getaddrinfo () indicates successful completion; a non-zero return value 
indicates failure. The possible values for the failures are listed in the ERRORS section. 

Upon successful return of getaddrinfo (), the location to which res points refers to a linked list of 
addrinfo structures, each of which specifies a socket address and information for use in creating 
a socket with which to use that socket address. The list shall include at least one addrinfo 
structure. The ai_next field of each structure contains a pointer to the next structure on the list, or 
a null pointer if it is the last structure on the list. Each structure on the list includes values for use 
with a call to the socket () function, and a socket address for use with the connect () function or, if 
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12485 the AI_PASSIVE flag was specified, for use with the bind() function. The fields ai_famity , 

12486 ai_socktype , and ai_protocol are usable as the arguments to the socket () function to create a socket 

12487 suitable for use with the returned address. The fields ai_addr and ai_addrlen are usable as the 

12488 arguments to the connect () or bind () functions with such a socket, according to the AI_PASSIVE 

12489 flag. 

12490 If nodename is not null, and if requested by the AI_CANONNAME flag, the ai_canonname field of 

12491 the first returned addrinfo structure points to a null-terminated string containing the canonical 

12492 name corresponding to the input nodename; if the canonical name is not available, then 

12493 aijcanonname refers to the nodename argument or a string with the same contents. The contents of 

12494 the ai_flags field of the returned structures are undefined. 

12495 All fields in socket address structures returned by getaddrinfo () that are not filled in through an 

12496 explicit argument (for example, sin6_flowinfo and sin_zero ) shall be set to zero. 

12497 Note: This makes it easier to compare socket address structures. 

12498 ERRORS 

12499 The freeaddrinfo () and getaddrinfo () functions shall fail and return the corresponding value if: 

12500 [EAI_AGAIN] The name could not be resolved at this time. Future attempts may succeed. 

12501 [EAI_BADFLAGS] 

12502 The flags parameter had an invalid value. 

12503 [EAI_FAIL] A non-recoverable error occurred when attempting to resolve the name. 

12504 [EAI_FAMILY] The address family was not recognized. 

12505 [EAI_MEMORY] There was a memory allocation failure when trying to allocate storage for the 

12506 return value. 

12507 [EAI_NONAME] The name does not resolve for the supplied parameters. 

12508 Neither nodename nor servname were supplied. At least one of these shall be 

12509 supplied. 

12510 [EAI_SERVICE] The service passed was not recognized for the specified socket type. 

12511 [EAI_SOCKTYPE] 

12512 The intended socket type was not recognized. 

12513 [EAI_SYSTEM] A system error occurred; the error code can be found in err no. 

12514 EXAMPLES 

12515 None. 

12516 APPLICATION USAGE 

12517 None. 

12518 RATIONALE 

12519 None. 

12520 FUTURE DIRECTIONS 

12521 None. 

12522 SEE ALSO 

12523 connect(), gethostbyname(), getipnodebyname(), getnameinfo(), getservbyname{ ), socket (), the 

12524 System Interface Definitions volume of IEEE Std. 1003.1-200x, <netdb.h>, <sys/socket.h> 
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12525 CHANGE HISTORY 

12526 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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12527 NAME 

12528 freehostent — network host database functions 

12529 SYNOPSIS 

12530 tinclude <netdb.h> 

12531 void freehostent (struct hostent *ptr) ; 

12532 DESCRIPTION 

12533 Refer to endhostent (). 
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12534 NAME 

12535 freopen — open a stream 

12536 Notes to Reviewers 

12537 This section ivith side shading will not appear in the final copy. - Ed. 

12538 The MAN codings will be changed to CX if accepted. 

12539 SYNOPSIS 

12540 tinclude <stdio.h> 

12541 FILE *f reopen (const char * filename, const char *mode, FILE * stream); 

12542 DESCRIPTION 

12543 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

12544 conflict between the requirements described here and the ISO C standard is unintentional. This I 

12545 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

12546 The freopen () function shall first attempt to flush the stream and close any file descriptor 

12547 associated with stream. Failure to flush or close the file successfully shall be ignored. The error 

12548 and end-of-file indicators for the stream shall be cleared. 

12549 The freopen () function shall open the file whose path name is the string pointed to by filename 

12550 and associate the stream pointed to by stream with it. The mode argument shall be used just as in 

12551 fopen{). 

12552 The original stream shall be closed regardless of whether the subsequent open succeeds. 

12553 xsi After a successful call to th efreopen() function, the orientation of the stream shall be cleared, the 

12554 encoding rule shall be cleared, and the associated mbstate_t object shall be set to describe an 

12555 initial conversion state. 

12556 man The largest value that can be represented correctly in an object of type off_t shall be established 

12557 as the offset maximum in the open file description. 

12558 RETURN VALUE 

12559 Upon successful completion, freopen () shall return the value of stream. Otherwise, a null pointer 

12560 cx shall be returned, and errno shall be set to indicate the error. 

12561 ERRORS 

12562 Th efreopen () function shall fail if: 

12563 cx [EACCES] Search permission is denied on a component of the path prefix, or the file 

12564 exists and the permissions specified by mode are denied, or the file does not 

12565 exist and write permission is denied for the parent directory of the file to be 

12566 created. 

12567 cx [EINTR] A signal was caught during freopen (). 

12568 cx [EISDIR] The named file is a directory and mode requires write access. 

12569 man [ELOOP] Too many symbolic links were encountered in resolving path. 

12570 cx [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 

12571 CX 

12572 

12573 

12574 CX 


[ENAMETOOLONG] 

The length of the filename exceeds |PATH_MAX} or a path name component is 
longer than |NAME_MAX} while _POSIX_NO_TRUNC is in effect. 

[ENFILE] The maximum allowable number of files is currently open in the system. 
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12575 cx [ENOENT] A component of filename does not name an existing file or filename is an empty 

12576 string. 

12577 cx [ENOSPC] The directory or file system that would contain the new file cannot be 

12578 expanded, the file does not exist, and it was to be created. 

12579 cx [ENOTDIR] A component of the path prefix is not a directory. 

12580 cx [ENXIO] The named file is a character special or block special file, and the device 

12581 associated with this special file does not exist. 

12582 man [EOVERFLOW] The named file is a regular file and the size of the file cannot be represented 

12583 correctly in an object of type off_t. 

12584 cx [EROFS] The named file resides on a read-only file system and mode requires write 

12585 access. 

12586 The freopen () function may fail if: 

12587 man [EINVAL] The value of the mode argument is not valid. 

12588 man [ENAMETOOLONG] 

12589 Path name resolution of a symbolic link produced an intermediate result 

12590 whose length exceeds |PATH_MAX}. 

12591 man [ENOMEM] Insufficient storage space is available. 

12592 man [ENXIO] A request was made of a nonexistent device, or the request was outside the 

12593 capabilities of the device. 

12594 man [ETXTBSY] The file is a pure procedure (shared text) file that is being executed and mode 

12595 requires write access. 

12596 EXAMPLES 

12597 Directing Standard Output to a File 

12598 The following example logs all standard output to the /tmp/logfile file. 

12599 #include <stdio.h> 

12600 

12601 FILE *fp; 

12602 

12603 fp = freopen ("/tmp/logfile", "a+", stdout); 

12604 

12605 APPLICATION USAGE 

12606 The freopen () function is typically used to attach the preopened streams associated with stdin, 

12607 stdout, and stderr to other files. 

12608 RATIONALE 

12609 None. 

12610 FUTURE DIRECTIONS 

12611 None. 

12612 SEE ALSO 

12613 fclose(), fopen(), fdopen(), mbsinit(), the System Interface Definitions volume of 

12614 IEEE Std. 1003.1-200x, <stdio.h> 
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12615 

12616 

12617 

12618 

12619 

12620 

12621 

12622 

12623 

12624 

12625 

12626 

12627 

12628 

12629 

12630 

12631 

12632 

12633 

12634 

12635 

12636 

12637 

12638 

12639 

12640 

12641 

12642 

12643 

12644 

12645 

12646 

12647 

12648 

12649 

12650 

12651 

12652 

12653 

12654 


CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

In the DESCRIPTION, the word “name" is replaced by "path name", to make it clear that the 
function is not limited to accepting file names only. 

In the ERRORS section: 

• The description of the [EMFILE] error has been changed to refer to |OPEN_MAX} file 
descriptors rather than {FOPEN_MAX} file descriptors, directories, and message catalogs. 

• The errors [EINVAL], [ENOMEM], and [ETXTBSY] are marked as extensions. 

• The [ENXIO] error is added in the "may fail" section and marked as an extension. 

The following change is incorporated for alignment with the ISO C standard: 

• The type of arguments filename and mode are changed from char* to const char*. 

The following change is incorporated for alignment with the FIPS requirements: 

• In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 
name component is larger that |NAME_MAX} is now defined as mandatory and marked as 
an extension. 

Issue 4, Version 2 

The ERRORS section is updated for X/OPEN UNIX conformance as follows: 

• It states that [ELOOP] is returned if too many symbolic links are encountered during path 
name resolution. 

• A second [ENAMETOOLONG] condition is defined that may report excessive length of an 
intermediate result of path name resolution of a symbolic link. 

Issue 5 

The DESCRIPTION is updated to indicate that the orientation of the stream is cleared and the 
conversion state of the stream is set to an initial conversion state by a successful call to the 
freopen () function. 

Large File Summit extensions are added. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 
This is since behavior may vary from one file system to another. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the DESCRIPTION, text is added to indicate setting of the offset maximum in the open file 
description. This change is to support large files. 

• In the ERRORS section, the [EOVERFLOW] condition is added. This change is to support 
large files. 

• The [ELOOP] mandatory error condition is added. 
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• A second [ENAMETOOLONG] is added as an optional error condition. 

. The [EINVAL], [ENOMEM], [ENXIO], and [ETXTBSY] optional error conditions are added. 
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NAME 

frexp — extract mantissa and exponent from a double precision number 

SYNOPSIS 

#include <math.h> 

double frexp(double num, int * exp ); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The frexp () function breaks a floating-point number into a normalized fraction and an integral 
power of 2. It stores the integer exponent in the int object pointed to by exp. 

An application wishing to check for error situations should set errno to 0 before calling /rexp( ). If 
errno is non-zero on return, or the return value is NaN, an error has occurred. 

RETURN VALUE 

The frexp () function shall return the value x, such that x is a double with magnitude in the 
interval ['/id) or 0, and num equals x times 2 raised to the power *exp. 

If num is 0, both parts of the result shall be 0. 

xsi If num is NaN, NaN shall be returned, errno may be set to [EDOM], and the value of *exp shall be 
unspecified. 

If num is ±Inf, mini shall be returned, errno may be set to [EDOM], and the value of *exp shall be 
unspecified. 

ERRORS 

The frexp () function may fail if: 
xsi [EDOM] The value of num is NaN or ±Inf. 

xsi No other errors shall occur. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

isnan (), ldexp(), modf(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

<math.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 
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12696 Issue 4 

12697 References to matherr () are removed. 

12698 The name of the first argument is changed from value to num. 

12699 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

12700 ISO C standard and to rationalize error handling in the mathematics functions. 

12701 The return value specified for [EDOM] is marked as an extension. 


12702 Issue 5 

12703 The DESCRIPTION is updated to indicate how an application should check for an error. This 

12704 text was previously published in the APPLICATION USAGE section. 
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12705 NAME 

12706 fscanf, scanf, sscanf — convert formatted input 

12707 SYNOPSIS 

12708 tinclude <stdio.h> 

12709 int fscanf (FILE * stream, const char * format, ... ) ; 

12710 int scanf (const char * format, ... ) ; 

12711 int sscanf (const char *s, const char * format , ... ) ; 

12712 DESCRIPTION 

12713 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

12714 conflict between the requirements described here and the ISO C standard is unintentional. This I 

12715 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

12716 The fscanf () function reads from the named input stream. The scanf() function reads from the 

12717 standard input stream stdin . The sscanf () function reads from the string s. Each function reads 

12718 bytes, interprets them according to a format, and stores the results in its arguments. Each 

12719 expects, as arguments, a control string format described below, and a set of pointer arguments 

12720 indicating where the converted input should be stored. The result is undefined if there are 

12721 insufficient arguments for the format. If the format is exhausted while arguments remain, the 

12722 excess arguments are evaluated but are otherwise ignored. 

12723 xsi Conversions can be applied to the n th argument after the format in the argument list, rather than 

12724 to the next unused argument. In this case, the conversion character ' %' (see below) is replaced 

12725 by the sequence "%n$", where n is a decimal integer in the range [1,{NL_ARGMAX}]. This 

12726 feature provides for the definition of format strings that select arguments in an order 

12727 appropriate to specific languages. In format strings containing the "%n$" form of conversion 

12728 specifications, it is unspecified whether numbered arguments in the argument list can be 

12729 referenced from the format string more than once. 

12730 Th e format can contain either form of a conversion specification—that is, ' %' or " %n$"—but the 

12731 two forms cannot normally be mixed within a single format string. The only exception to this is 

12732 that " % % " or " % * " can be mixed with the " % n $ " form. 

12733 The fscanf () function in all its forms allows for detection of a language-dependent radix 

12734 character in the input string. The radix character is defined in the program's locale (category 

12735 LC_NUMERIC). In the POSIX locale, or in a locale where the radix character is not defined, the 

12736 radix character defaults to a period (' .'). 

12737 The format is a character string, beginning and ending in its initial shift state, if any, composed 

12738 of zero or more directives. Each directive is composed of one of the following: one or more 

12739 white-space characters (<space>, <tab>, <newline>, <vertical-tab>, or <form-feed> characters); 

12740 an ordinary character (neither ' %' nor a white-space character); or a conversion specification. 

12741 xsi Each conversion specification is introduced by the character ' %' or the character sequence 

12742 " % n $", after which the following appear in sequence: 

12743 • An optional assignment-suppressing character ' *'. 

12744 • An optional non-zero decimal integer that specifies the maximum field width. 

12745 • An optional size modifier h, l (ell), or L indicating the size of the receiving object. The I 

12746 application shall ensure that the conversion characters d, i, and n are preceded by h if the I 

12747 corresponding argument is a pointer to short int rather than a pointer to int, or by l (ell) if it I 

12748 is a pointer to long int. Similarly, the conversion characters o, u, and x shall be preceded by li I 

12749 if the corresponding argument is a pointer to unsigned short int rather than a pointer to I 

12750 unsigned int, or by l (ell) if it is a pointer to unsigned long int. The conversion characters e,f I 

12751 and g shall be preceded by l (ell) if the corresponding argument is a pointer to double rather I 
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than a pointer to float, or by L if it is a pointer to long double. Finally, the conversion 
characters c, s, and ' [' shall be preceded by l (ell) if the corresponding argument is a pointer I 
to wchar_t rather than a pointer to a character type. If an h, l (ell), or L appears with any other 
conversion character, the behavior is undefined. 

• A conversion character that specifies the type of conversion to be applied. The valid 
conversion characters are described below. 

The fscanf ( ) functions execute each directive of the format in turn. If a directive fails, as detailed 
below, the function shall return. Failures are described as input failures (due to the 
unavailability of input bytes) or matching failures (due to inappropriate input). 

A directive composed of one or more white-space characters is executed by reading input until 
no more valid input can be read, or up to the first byte which is not a white-space character 
which remains unread. 

A directive that is an ordinary character is executed as follows. The next byte is read from the 
input and compared with the byte that comprises the directive; if the comparison shows that 
they are not equivalent, the directive fails, and the differing and subsequent bytes remain 
unread. 

A directive that is a conversion specification defines a set of matching input sequences, as 
described below for each conversion character. A conversion specification is executed in the 
following steps: 

Input white-space characters (as specified by isspace( )) are skipped, unless the conversion 
specification includes a ' [', c, C, or n conversion character. 

An item is read from the input, unless the conversion specification includes an n conversion 
character. An input item is defined as the longest sequence of input bytes (up to any specified 
maximum field width, which may be measured in characters or bytes dependent on the 
conversion character) which is an initial subsequence of a matching sequence. The first byte, if 
any, after the input item remains unread. If the length of the input item is 0, the execution of the 
conversion specification fails; this condition is a matching failure, unless end-of-file, an encoding 
error, or a read error prevented input from the stream, in which case it is an input failure. 

Except in the case of a ' %' conversion character, the input item (or, in the case of a %n 
conversion specification, the count of input bytes) is converted to a type appropriate to the 
conversion character. If the input item is not a matching sequence, the execution of the 
conversion specification fails; this condition is a matching failure. Unless assignment 
suppression was indicated by a ' *', the result of the conversion is placed in the object pointed 
to by the first argument following the format argument that has not already received a 
xsi conversion result if the conversion specification is introduced by ' %', or in the nth argument if 
introduced by the character sequence " %n$ ". If this object does not have an appropriate type, or 
if the result of the conversion cannot be represented in the space provided, the behavior is 
undefined. 

The following conversion characters are valid: 

d Matches an optionally signed decimal integer, whose format is the same as expected for 

the subject sequence of strtol() with the value 10 for the base argument. In the absence I 
of a size modifier, the application shall ensure that the corresponding argument is a I 
pointer to int. I 

i Matches an optionally signed integer, whose format is the same as expected for the 

subject sequence of strtol() with 0 for the base argument. In the absence of a size I 
modifier, the application shall ensure that the corresponding argument is a pointer to I 

int. 
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o Matches an optionally signed octal integer, whose format is the same as expected for 

the subject sequence of strtoul() with the value 8 for the base argument. In the absence I 

of a size modifier, the application shall ensure that the corresponding argument is a I 

pointer to unsigned int. I 

u Matches an optionally signed decimal integer, whose format is the same as expected for 

the subject sequence of strtoul() with the value 10 for the base argument. In the absence I 

of a size modifier, the application shall ensure that the corresponding argument is a I 

pointer to unsigned int. I 

x Matches an optionally signed hexadecimal integer, whose format is the same as 

expected for the subject sequence of strtoid () with the value 16 for the base argument. In I 
the absence of a size modifier, the application shall ensure that the corresponding I 
argument is a pointer to unsigned int. I 

e,f,g Matches an optionally signed floating-point number, whose format is the same as 

expected for the subject sequence of strtod(). In the absence of a size modifier, the I 
application shall ensure that the corresponding argument is a pointer to float. I 

If th efprintf( ) family of functions generates character string representations for infinity 
and NaN (a 7858 symbolic entity encoded in floating-point format) to support the 
IEEE Std. 754:1985 standard, the fscanf () family of functions shall recognize them as 
input. 

s Matches a sequence of bytes that are not white-space characters. The application shall I 

ensure that the corresponding argument is a pointer to the initial byte of an array of I 
char, signed char, or unsigned char large enough to accept the sequence and a 
terminating null character code, which shall be added automatically. 

If an / (ell) qualifier is present, the input is a sequence of characters that begins in the 
initial shift state. Each character is converted to a wide character as if by a call to the 
mbrtowc () function, with the conversion state described by an mbstate_t object 
initialized to zero before the first character is converted. The application shall ensure I 

that the corresponding argument is a pointer to an array of wchar_t large enough to I 

accept the sequence and the terminating null wide character, which shall be added 
automatically. 

[ Matches a non-empty sequence of bytes from a set of expected bytes (the scanset). The 

normal skip over white-space characters is suppressed in this case. The application I 
shall ensure that the corresponding argument is a pointer to the initial byte of an array I 
of char, signed char, or unsigned char large enough to accept the sequence and a I 
terminating null byte, which shall be added automatically. 

If an l (ell) qualifier is present, the input is a sequence of characters that begins in the 
initial shift state. Each character in the sequence is converted to a wide character as if 
by a call to the mbrtowc () function, with the conversion state described by an mbstate_t 
object initialized to zero before the first character is converted. The application shall I 
ensure that the corresponding argument is a pointer to an array of wchar_t large I 
enough to accept the sequence and the terminating null wide character, which shall be 
added automatically. 

The conversion specification includes all subsequent bytes in the format string up to 
and including the matching right square bracket (' ] '). The bytes between the square 
brackets (the scanlist) comprise the scanset, unless the byte after the left square bracket 
is a circumflex (' ''), in which case the scanset contains all bytes that do not appear in 
the scanlist between the circumflex and the right square bracket. If the conversion 
specification begins with " [ ] " or the right square bracket is included in the 
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scanlist and the next right square bracket is the matching right square bracket that ends 
the conversion specification; otherwise, the first right square bracket is the one that 
ends the conversion specification. If a ' - ' is in the scanlist and is not the first character, 
nor the second where the first character is a ' "', nor the last character, the behavior is 
implementation-dependent. 

c Matches a sequence of bytes of the number specified by the field width (1 if no field 

width is present in the conversion specification). The application shall ensure that the I 
corresponding argument is a pointer to the initial byte of an array of char, signed char, I 
or unsigned char large enough to accept the sequence. No null byte is added. The 
normal skip over white-space characters is suppressed in this case. 

If an / (ell) qualifier is present, the input is a sequence of characters that begins in the 
initial shift state. Each character in the sequence is converted to a wide character as if 
by a call to the mbrtowc {) function, with the conversion state described by an mbstate_t 
object initialized to zero before the first character is converted. The application shall I 
ensure that the corresponding argument is a pointer to an array of wchar_t large I 
enough to accept the resulting sequence of wide characters. No null wide character is 
added. 

p Matches an implementation-dependent set of sequences, which shall be the same as the I 

set of sequences that is produced by the %p conversion of the corresponding fprintf() I 
functions. The application shall ensure that the corresponding argument is a pointer to I 
a pointer to void. The interpretation of the input item is implementation-dependent. If I 
the input item is a value converted earlier during the same program execution, the 
pointer that results shall compare equal to that value; otherwise, the behavior of the %p 
conversion is undefined. 

n No input is consumed. The application shall ensure that the corresponding argument is I 

a pointer to the integer into which is to be written the number of bytes read from the I 
input so far by this call to the fscanf () functions. Execution of a %n conversion I 
specification does not increment the assignment count returned at the completion of 
execution of the function. 


xsi C Same as Ic. 

xsi S Same as Is. 

% Matches a single ' %'; no conversion or assignment occurs. The complete conversion I 

specification shall be " % % ". I 

If a conversion specification is invalid, the behavior is undefined. 

The conversion characters E, G, and X are also valid and behave the same as, respectively, e, g, 
and x. 

If end-of-file is encountered during input, conversion is terminated. If end-of-file occurs before 
any bytes matching the current conversion specification (except for %n) have been read (other 
than leading white-space characters, where permitted), execution of the current conversion 
specification terminates with an input failure. Otherwise, unless execution of the current 
conversion specification is terminated with a matching failure, execution of the following 
conversion specification (if any) is terminated with an input failure. 

Reaching the end of the string in sscanf () is equivalent to encountering end-of-file for fscanf (). 

If conversion terminates on a conflicting input, the offending input is left unread in the input. 
Any trailing white space (including newline characters) is left unread unless matched by a 
conversion specification. The success of literal matches and suppressed assignments is only 


System Interfaces, Issue 6 


401 



fscanf () 


System Interfaces 


12893 directly determinable via the %n conversion specification. 

12894 The fscanf () and scanf() functions may mark the st_atime field of the file associated with stream 

12895 for update. The st_atime field shall be marked for update by the first successful execution of 

12896 fgetc( ),fgets( ),fread(), getc( ), getchar( ), gets (), fscanf (), or fscanf () using stream that returns data 

12897 not supplied by a prior call to ungetc (). 

12898 RETURN VALUE 

12899 Upon successful completion, these functions shall return the number of successfully matched 

12900 and assigned input items; this number can be 0 in the event of an early matching failure. If the 

12901 input ends before the first matching failure or conversion, EOF shall be returned. If a read error 

12902 cx occurs, the error indicator for the stream is set, EOF shall be returned, and errno shall be set to 

12903 indicate the error. 

12904 ERRORS 

12905 For the conditions under which the fscanf () functions fail and may fail, refer to fgetc() or 

12906 fgetwc(). 

12907 In addition, fscanf () may fail if: 

12908 xsi [EILSEQ] Input byte sequence does not form a valid character. 

12909 xsi [EINVAL] There are insufficient arguments. 

12910 EXAMPLES 

12911 The call: 

12912 int i, n; float x; char name [50]; 

12913 n = scant (" %d%f%s", &i, &x, name); 

12914 with the input line: 

12915 2 5 5 4.32E—1 Hamster 

12916 assigns to n the value 3, to i the value 25, to x the value 5.432, and name contains the string 

12917 "Hamster". 

12918 The call: 

12919 int i; float x; char name [50]; 

12920 (void) scant ( "%2d%f%*d %[ 012345 678 9 ]" , &i, &x, name); 

12921 with input: 

12922 5 6 7 8 9 0 1 2 3 5 6 a72 

12923 assigns 56 to i, 789.0 to x, skips 0123, and places the string "56\0" in name. The next call to 

12924 getclmr( ) shall return the character ' a'. 

12925 Reading Data into an Array 

12926 The following call uses fscanf () to read three floating point numbers from standard input into 

12927 the input array. 

12928 float input [3]; 

12929 fscanf (stdin, "%f %f %f", input, input + 1, input+2); 

12930 APPLICATION USAGE 

12931 If the application calling fscanf () has any objects of type wint_t or wchar_t, it must also include 

12932 the <wchar.h> header to have these objects defined. 
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12933 RATIONALE 

12934 None. 

12935 FUTURE DIRECTIONS 

12936 None. 

12937 SEE ALSO 

12938 gefc(), printf( ), setlocale( ), strtod (), strtol(), strtonl(), wcrtomb( ), the System Interface Definitions 

12939 volume of IEEE Std. 1003.1-200x, <langinfo.h>, <stdio.h>, <wchar.h>, the System Interface I 

12940 Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale I 

12941 CHANGE HISTORY 

12942 First released in Issue 1. 

12943 Derived from Issue 1 of the SVID. 

12944 Issue 4 

12945 Use of the terms "byte" and "character" is rationalized to make it clear when single-byte and 

12946 multi-byte values can be used. Similarly, use of the terms "conversion specification" and 

12947 "conversion character" is now more precise. 

12948 Various errors are corrected. For example, the description of the d conversion character 

12949 contained an erroneous reference to strtod() in Issue 3. This is replaced in this issue by reference 

12950 to strtol(). 

12951 The DESCRIPTION is updated in a number of places to indicate further implications of the 

12952 "%n$" form of a conversion. All references to this functionality, which is not specified in the 

12953 ISO C standard, are marked as extensions. 

12954 The ERRORS section is changed to refer to the entries for fgetc() and fgetwc{ ), the [EINVAL] 

12955 error is marked as an extension, and the [EILSEQ] error is added and marked as an extension. 

12956 The detailed description of this function including the CHANGE HISTORY section for scanf( ) is 

12957 provided here instead of under scanf( ). 

12958 The APPLICATION USAGE section is amended to record the need for <sys/types.h> or 

12959 <stddef.h> if type wchar_t is required. 

12960 The following changes are incorporated for alignment with the ISO C standard: 

12961 • The type of the argument format for all functions, and the type of argument s for sscanf( ), are 

12962 changed from char* to const char*. 

12963 • The description is updated in various places to align more closely with the text of the ISO C 

12964 standard. In particular, this issue fully defines the L conversion character, allows for the 

12965 support of multi-byte coded character sets (although these are not mandated by X/Open), 

12966 and fills in a number of gaps in the definition (for example, by defining termination 

12967 conditions for sscanf( ). 

12968 • Following an ANSI interpretation, the effect of conversion specifications that consume no 

12969 input is better defined, and is no longer marked as an extension. 

12970 The following change is incorporated for alignment with the MSE working draft. 

12971 • The C and S conversion characters are added, indicating a pointer in the argument list to the 

12972 initial wide-character code of an array large enough to accept the input sequence. 
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12973 

12974 

12975 

12976 

12977 

12978 

12979 

12980 

12981 


Issue 5 

Aligned with ISO/IEC 9899:1990/Amendment 1:1995 (E). Specifically, the l (ell) qualifier is now 
defined for the c, s, and ' [' conversion characters. 

The DESCRIPTION is updated to indicate that if infinity and NaN can be generated by the 
/print /{) family of functions, then they are recognized by the fscanf () family. 

Issue 6 

The Open Group corrigenda items U021/7 and U028/10 have been applied. These correct 
several occurrences of "characters" in the text which have been replaced with the term "bytes". 

The DESCRIPTION is updated to avoid use of the term "must" for application requirements. 
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12982 NAME 

12983 fseek, fseeko — reposition a file-position indicator in a stream 

12984 SYNOPSIS 

12985 tinclude <stdio.h> 

12986 int fseek (FILE * stream, long int offset, int whence) ; 

12987 cx int fseeko (FILE * stream, off_t offset, int whence ); 

12988 

12989 DESCRIPTION 

12990 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

12991 conflict between the requirements described here and the ISO C standard is unintentional. This I 

12992 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

12993 Th efseek( ) function shall set the file-position indicator for the stream pointed to by stream. 

12994 The new position, measured in bytes from the beginning of the file, shall be obtained by adding 

12995 offset to the position specified by whence. The specified point is the beginning of the file for 

12996 {SEEK_SET[, the current value of the file-position indicator for {SEEK_CUR}, or end-of-file for 

12997 {SEEK_END(. 

12998 If the stream is to be used with wide-character input/output functions, the application shall I 

12999 ensure that offset is either 0 or a value returned by an earlier call to / tell () on the same stream and I 

13000 whence is {SEEK_SET}. I 

13001 A successful call to fseek( ) shall clear the end-of-file indicator for the stream and undo any effects 

13002 of nngetc() and ungetwc{ ) on the same stream. After an fseek () call, the next operation on an 

13003 update stream may be either input or output. 

13004 If the most recent operation, other than ftell (), on a given stream is fflush (), the file offset in the 

13005 underlying open file description shall be adjusted to reflect the location specified by fseek( ). 

13006 Th efseek() function shall allow the file-position indicator to be set beyond the end of existing 

13007 data in the file. If data is later written at this point, subsequent reads of data in the gap shall 

13008 return bytes with the value 0 until data is actually written into the gap. 

13009 cx The behavior of fseek( ) on devices which are incapable of seeking is implementation-dependent. 

13010 The value of the file offset associated with such a device is undefined. 

13011 If the stream is writable and buffered data had not been written to the underlying file, fseek() 

13012 shall cause the unwritten data to be written to the file and shall mark the st_ctime and stjntime 

13013 fields of the file for update. 

13014 In a locale with state-dependent encoding, whether fseek( ) restores the stream's shift state is 

13015 implementation-dependent. 

13016 The fseeko( ) function is identical to th efseek( ) function except that the offset argument is of type 

13017 off_t. 

13018 RETURN VALUE 

13019 cx Th efseek( ) and fseeko ( ) functions shall return 0 if they succeed. 

13020 cx Otherwise, they shall return -1 and set errno to indicate the error. 

13021 ERRORS 

13022 cx The fseek () and fseeko() functions shall fail if, either the stream is unbuffered or the stream's 

13023 cx buffer needed to be flushed, and the call to fseek() or fseeko () causes an underlying lseek() or 

13024 write( ) to be invoked: 
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13025 cx [EAGAIN] The 0_N0NBL0CK flag is set for the file descriptor and the process would be 

13026 delayed in the write operation. 

13027 cx [EBADF] The file descriptor underlying the stream file is not open for writing or the 

13028 stream's buffer needed to be flushed and the file is not open. 

13029 man [EFBIG] An attempt was made to write a file that exceeds the maximum file size. 

13030 xsi [EFBIG] An attempt was made to write a file that exceeds the process' file size limit. 

13031 man [EFBIG] The file is a regular file and an attempt was made to write at or beyond the 

13032 offset maximum associated with the corresponding stream. 


13033 cx [EINTR] The write operation was terminated due to the receipt of a signal, and no data 

13034 was transferred. 


13035 cx [EINVAL] The whence argument is invalid. The resulting file-position indicator would be 

13036 set to a negative value. 

13037 cx [EIO] A physical I/O error has occurred, or the process is a member of a 

13038 background process group attempting to perform a write{) to its controlling 

13039 terminal, TOSTOP is set, the process is neither ignoring nor blocking 

13040 SIGTTOU, and the process group of the process is orphaned. This error may 

13041 also be returned under implementation-dependent conditions. 

13042 cx [ENOSPC] There was no free space remaining on the device containing the file. 

13043 man [EOVERFLOW] For fseek( ), the resulting file offset would be a value which cannot be 

13044 represented correctly in an object of type long. 

13045 man [EOVERFLOW] For fseeko(), the resulting file offset would be a value which cannot be 

13046 represented correctly in an object of type off_t. 

13047 cx [EPIPE] The file descriptor underlying stream is associated with a pipe or FIFO. 

13048 cx [EPIPE] An attempt was made to write to a pipe or FIFO that is not open for reading 

13049 by any process; a SIGPIPE signal shall also be sent to the thread. 

13050 man [ENXIO] A request was made of a nonexistent device, or the request was outside the 

13051 capabilities of the device. 


13052 EXAMPLES 

13053 None. 

13054 APPLICATION USAGE 

13055 None. 

13056 RATIONALE 

13057 None. 

13058 FUTURE DIRECTIONS 

13059 None. 

13060 SEE ALSO 

13061 fopen(),fsetpos(),ftell(),getrlimit(), rewind(), ulimit(), nngetc(), the System Interface Definitions 

13062 volume of IEEE Std. 1003.1-200x, <stdio.h> 

13063 CHANGE HISTORY 

13064 First released in Issue 1. 

13065 Derived from Issue 1 of the SVID. 
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13066 

13067 

13068 

13069 

13070 

13071 

13072 

13073 

13074 

13075 

13076 

13077 

13078 

13079 

13080 

13081 

13082 

13083 

13084 

13085 

13086 

13087 

13088 

13089 

13090 

13091 

13092 

13093 

13094 

13095 

13096 

13097 

13098 

13099 

13100 

13101 


Issue 4 

In the DESCRIPTION, the words "The seek () function does not, by itself, extend the size of a 
file" are deleted. 

In the RETURN VALUE section, the value -1 is marked as an extension. This is because the 
ISO POSIX-1 standard only requires that a non-zero value is returned. 

In the ERRORS section, text is added to indicate that error returns are only generated when 
either the stream is unbuffered, or if the stream buffer needs to be flushed. 

The "fail" and "may fail" parts of the ERRORS section are revised for consistency with lseek () 
and write (). 

Text associated with the [EIO] error is expanded and the [ENXIO] error is added. 

Text is added to explain how fseek() is used with wide-character input/output; this is marked as 
a WP extension. 

The [EFBIG] error is marked to show extensions. 

The APPLICATION USAGE section is added. 

The following change is incorporated for alignment with the ISO C standard: 

• The type of argument offset is now defined in full as long int instead of long. 

The following change is incorporated for alignment with the FIPS requirements: 

• The [EINTR] error is no longer an indication that the implementation does not report partial 
transfers. 

Issue 4, Version 2 

In the ERRORS section, the description of [EIO] is updated to include the case where a physical 
I/O error occurs. 

Issue 5 

Normative text previously in the APPLICATION USAGE section is moved to the 
DESCRIPTION. 

Large File Summit extensions are added. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• Th efseeko() function is added. 

• The [EFBIG], [EOVERFLOW], and [ENXIO] mandatory error conditions are added. 

The following change is incorporated for alignment with the FIPS requirements: 

• The [EINTR] error is no longer an indication that the implementation does not report partial 
transfers. 

The DESCRIPTION is updated to avoid use of the term "must" for application requirements. 
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13102 

13103 

13104 

13105 

13106 

13107 

13108 

13109 

13110 

13111 

13112 

13113 

13114 

13115 

13116 

13117 

13118 

13119 

13120 

13121 

13122 

13123 

13124 

13125 

13126 

13127 

13128 

13129 

13130 

13131 

13132 

13133 

13134 

13135 

13136 

13137 

13138 

13139 

13140 

13141 

13142 


NAME 

fsetpos — set current file position 

SYNOPSIS 

#include <stdio.h> 

int fsetpos(FILE * stream, const fpos_t *pos ); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The fsetpos () function shall set the file position and state indicators for the stream pointed to by 
stream according to the value of the object pointed to by pos, which the application shall ensure I 
is a value obtained from an earlier call to fgetpos () on the same stream. I 

A successful call to th e fsetpos() function shall clear the end-of-file indicator for the stream and 
undo any effects of nngetc( ) on the same stream. After an fsetpos () call, the next operation on an 
update stream may be either input or output. 

RETURN VALUE 

The fsetpos () function shall return 0 if it succeeds; otherwise, it shall return a non-zero value and 
set errno to indicate the error. 

ERRORS 

The fsetpos () function may fail if: 

cx [EBADF] The file descriptor underlying stream is not valid. 

cx [ESPIPE] The file descriptor underlying stream is associated with a pipe, FIFO, or socket. I 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

fopen (), ftell(), rewind (), ungetc(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <stdio.h> 

CHANGE HISTORY 

First released in Issue 4. 

Derived from the ISO C standard. 


Issue 6 

Extensions beyond the ISO C standard are now marked. 

An additional [ESPIPE] error condition is added for sockets. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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NAME 

fstat — get file status 

SYNOPSIS 

#include <sys/stat.h> 

int fstat(int fildes, struct stat *buf) ; 

DESCRIPTION 

The fstat () function obtains information about an open file associated with the file descriptor 
fildes, and writes it to the area pointed to by buf. 

shm If fildes references a shared memory object, the implementation need update in the stat structure 

pointed to by the buf argument only the st_uid, st_gid, st_size, and st_mode fields, and only the 
S JRUSR, SJWUSR, SJRGRP, S JWGRP, SJROTH, and SJWOTH file permission bits need be 
valid. 

tym If fildes references a typed memory object, the implementation need update in the stat structure I 

pointed to by the buf argument only the st_uid, st_gid, st_size, and st_mode fields, and only the I 
S JRUSR, SJWUSR, SJRGRP, SJWGRP, SJROTH, and SJWOTH file permission bits need be I 
valid. I 

The buf argument is a pointer to a stat structure, as defined in <sys/stat.h>, into which I 
information is placed concerning the file. 

The structure members stjnode, st_ino, st_dev, st_uid, st_gid, st_atime, st_ctime, and stjntime 
shall have meaningful values for all file types defined in this volume of IEEE Std. 1003.1-200x. 
The value of the member st_nlink shall be set to the number of links to the file. 

An implementation that provides additional or alternative file access control mechanisms may, 
under implementation-dependent conditions, caus e fstat () to fail. 

The fstat () function updates any time-related fields as described in File Times Update (see the I 
System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 6, Character Set), before I 
writing into the stat structure. I 

RETURN VALUE 

Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 
indicate the error. 

ERRORS 

The fstat () function shall fail if: 

[EBADF] The fildes argument is not a valid file descriptor. 

man [EIO] An I/O error occurred while reading from the file system. 

man [EOVERFLOW] The file size in bytes or the number of blocks allocated to the file or the file 

serial number cannot be represented correctly in the structure pointed to by 
buf. 

The fstat () function may fail if: 

man [EOVERFLOW] One of the values is too large to store into the structure pointed to by the buf 

argument. 


System Interfaces, Issue 6 


409 



fstat() 


System Interfaces 


13182 EXAMPLES 

13183 Obtaining File Status Information 

13184 The following example shows how to obtain file status information for a file named 

13185 /home/cnd/modl. The structure variable buffer is defined for the stat structure. The 

13186 /home/cnd/modl file is opened with read/write privileges and is passed to the open file 

13187 descriptor fildes . 

13188 #include <sys/types .h> 

13189 tinclude <sys/stat.h> 

13190 #include <fcntl.h> 

13191 struct stat buffer; 

13192 int status; 

13193 

13194 fildes = open ("/home/cnd/modl " , 0_RDWR) ; 

13195 status = fstat (fildes, Sbuffer) ; 

13196 APPLICATION USAGE 

13197 None. 

13198 RATIONALE 

13199 None. 

13200 FUTURE DIRECTIONS 

13201 None. 

13202 SEE ALSO 

13203 lstat(), stat(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <sys/stat.h>, 

13204 <sys/types.h> 

13205 CHANGE HISTORY 

13206 First released in Issue 1. 

13207 Derived from Issue 1 of the SVID. 

13208 Issue 4 

13209 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

13210 XSI-conformant systems. 

13211 The following changes are incorporated in the DESCRIPTION for alignment with the 

13212 ISO POSIX-1 standard: 

13213 • A paragraph defining the contents of stat structure members is added. 

13214 • The words "extended security controls" are replaced by "additional or alternative file access 

13215 control mechanisms". 

13216 Issue 4, Version 2 

13217 The ERRORS section is updated for X/OPEN UNIX conformance as follows: 

13218 • The [EIO] error is added as a mandatory error indicated the occurrence of an I/O error. 

13219 • The [EOVERFLOW] error is added as an optional error indicating that one of the values is 

13220 too large to store in the area pointed to by buf. 
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13221 Issue 5 

13222 The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 

13223 Large File Summit extensions are added. 

13224 Issue 6 

13225 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

13226 The following new requirements on POSIX implementations derive from alignment with the 

13227 Single UNIX Specification: 

13228 • The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 

13229 required for conforming implementations of previous POSIX specifications, it was not 

13230 required for UNIX applications. 

13231 • The [EIO] mandatory error condition is added. 

13232 • The [EOVERFLOW] mandatory error condition is added. This change is to support large 

13233 files. 

13234 • The [EOVERFLOW] optional error condition is added. 

13235 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that I 

13236 shared memory object semantics apply to typed memory objects. I 
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13237 NAME 

13238 fstatvfs, statvfs — get file system information 

13239 SYNOPSIS 

13240 xsi tinclude <sys/statvf s .h> 

13241 int fstatvfs (int fildes, struct statvfs *buf) ; 

13242 int statvfs (const char *path, struct statvfs *buf) ; 

13243 

13244 DESCRIPTION 

13245 The fstatvfs () function obtains information about the file system containing the file referenced by 

13246 fildes. 

13247 The following flags can be returned in the f_flag member: 

13248 ST_RDONLY Read-only file system. 

13249 ST_NOSUID Setuid/setgid bits ignored by exec. 

13250 The statvfs () function obtains descriptive information about the file system containing the file 

13251 named by path. 

13252 For both functions, the buf argument is a pointer to a statvfs structure that shall be filled. Read, 

13253 write, or execute permission of the named file is not required, but the application shall ensure I 

13254 that all directories listed in the path name leading to the file are searchable. I 

13255 It is unspecified whether all members of the statvfs structure have meaningful values on all file 

13256 systems. 

13257 RETURN VALUE 

13258 Upon successful completion, statvfs() shall return 0. Otherwise, it shall return -1 and set errno to 

13259 indicate the error. 

13260 ERRORS 

13261 The fstatvfs () and statvfs () functions shall fail if: 

13262 [EIO] An I/O error occurred while reading the file system. 

13263 [EINTR] A signal was caught during execution of the function. 

13264 [EOVERFLOW] One of the values to be returned cannot be represented correctly in the 

13265 structure pointed to by buf. 

13266 The fstatvfs () function shall fail if: 

13267 [EBADF] The fildes argument is not an open file descriptor. 

13268 The statvfs () function shall fail if: 

13269 [EACCES] Search permission is denied on a component of the path prefix. 

13270 [ELOOP] Too many symbolic links were encountered in resolving path. 

13271 [ENAMETOOLONG] 

13272 The length of a path name exceeds {PATH_MAX}, or a path name component 

13273 is longer than |NAME_MAX}. 

13274 [ENOENT] A component of path does not name an existing file or path is an empty string. 

13275 [ENOTDIR] A component of the path prefix of path is not a directory. 

13276 The statvfs () function may fail if: 
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13277 [ENAMETOOLONG] 

13278 Path name resolution of a symbolic link produced an intermediate result 

13279 whose length exceeds |PATH_MAX}. 

13280 EXAMPLES 

13281 Obtaining File System Information Using fstatvfsl) 

13282 The following example shows how to obtain file system information for the file system upon 

13283 which the file named /home/cnd/modl resides, using the fstatvfs () function. The 

13284 /home/cnd/modl file is opened with read/write privileges and the open file descriptor is passed 

13285 to th efstatvfs () function. 

13286 tinclude <statvfs.h> 

13287 #include <fcntl.h> 

13288 struct statvfs buffer; 

13289 int status; 

13290 

13291 fildes = open ("/home/cnd/modl " , 0_RDWR) ; 

13292 status = fstatvfs (fildes, Sbuffer) ; 

13293 Obtaining File System Information Using statvfs( ) 

13294 The following example shows how to obtain file system information for the file system upon 

13295 which the file named /home/cnd/modl resides, using the statvfs () function. 

13296 tinclude <statvfs.h> 

13297 struct statvfs buffer; 

13298 int status; 

13299 

13300 status = statvfs ("/home/cnd/modl" , Sbuffer) ; 

13301 APPLICATION USAGE 

13302 None. 

13303 RATIONALE 

13304 None. 

13305 FUTURE DIRECTIONS 

13306 None. 

13307 SEE ALSO 

13308 chmod(), clioivn(), creat(), dnp(), exec, fcntl(), link(), mknod{), open(), pipe(), read(), time(), 

13309 unlink(), iitime(), write{), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

13310 <sys/statvfs.h> 

13311 CHANGE HISTORY 

13312 First released in Issue 4, Version 2. 

13313 Issue 5 

13314 Moved from X/OPEN UNIX extension to BASE. 

13315 Large File Summit extensions are added. 
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13316 Issue 6 

13317 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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13318 NAME 

13319 fsync — synchronize changes to a file 

13320 SYNOPSIS 

13321 FSC #include <unistd.h> 

13322 int fsync (int fildes) ; 

13323 

13324 DESCRIPTION 

13325 The fsync () function can be used by an application to indicate that all data for the open file 

13326 description named by fildes is to be transferred to the storage device associated with the file 

13327 described by fildes in an implementation-dependent manner. The fsync() function shall not 

13328 return until the system has completed that action or until an error is detected. 

13329 sio If _POSIX_SYNCHRONIZED_IO is defined, the fsync( ) function shall force all currently queued 

13330 I/O operations associated with the file indicated by file descriptor fildes to the synchronized I/O 

13331 completion state. All I/O operations shall be completed as defined for synchronized I/O file 

13332 integrity completion. 

13333 RETURN VALUE 

13334 Upon successful completion, fsync( ) shall return 0. Otherwise, -1 shall be returned and errno set 

13335 to indicate the error. If th e fsync( ) function fails, outstanding I/O operations are not guaranteed 

13336 to have been completed. 

13337 ERRORS 

13338 The fsync () function shall fail if: 

13339 [EBADF] The fildes argument is not a valid descriptor. 

13340 [EINTR] The fsync () function was interrupted by a signal. 

13341 man [EINVAL] The fildes argument does not refer to a file on which this operation is possible. 

13342 man [EIO] An I/O error occurred while reading from or writing to the file system. 

13343 In the event that any of the queued I/O operations fa iI,/sync() shall return the error conditions 

13344 defined for read( ) and write( ). 

13345 EXAMPLES 

13346 None. 

13347 APPLICATION USAGE 

13348 The fsync () function should be used by programs which require modifications to a file to be 

13349 completed before continuing; for example, a program which contains a simple transaction 

13350 facility might use it to ensure that all modifications to a file or files caused by a transaction are 

13351 recorded. 

13352 RATIONALE 

13353 The fsync () function is intended to force a physical write of data from the buffer cache, and to I 

13354 assure that after a system crash or other failure that all data up to the time of the fsync () call is 

13355 recorded on the disk. Since the concepts of "buffer cache", "system crash", "physical write", and 

13356 "non-volatile storage" are not defined here, the wording has to be more abstract. 

13357 If _POSIX_SYNCHRONIZED_IO is not defined, the wording relies heavily on the conformance 

13358 document to tell the user what can be expected from the system. It is explicitly intended that a 

13359 null implementation is permitted. This could be valid in the case where the system cannot assure 

13360 non-volatile storage under any circumstances or when the system is highly fault-tolerant and the 

13361 functionality is not required. In the middle ground between these extremes , fsync() might or 

13362 might not actually cause data to be written where it is safe from a power failure. The 
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13363 conformance document should identify at least that one configuration exists (and how to obtain 

13364 that configuration) where this can be assured for at least some files that the user can select to use 

13365 for critical data. It is not intended that an exhaustive list is required, but rather sufficient 

13366 information is provided to let the user determine that if he or she has critical data he or she can 

13367 configure her system to allow it to be written to non-volatile storage. 

13368 It is reasonable to assert that the key aspects of fsync () are unreasonable to test in a test suite. 

13369 That does not make the function any less valuable, just more difficult to test. A formal 

13370 conformance test should probably force a system crash (power shutdown) during the test for 

13371 this condition, but it needs to be done in such a way that automated testing does not require this 

13372 to be done except when a formal record of the results is being made. It would also not be 

13373 unreasonable to omit testing for fsync ( ), allowing it to be treated as a quality-of-implementation 

13374 issue. 

13375 FUTURE DIRECTIONS 

13376 None. 

13377 SEE ALSO 

13378 sync( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

13379 CHANGE HISTORY 

13380 First released in Issue 3. 

13381 Issue 4 

13382 The <unistd.h> header is added to the SYNOPSIS section. 

13383 In the APPLICATION USAGE section, the words "require a file to be in a known state" are 

13384 replaced by "require modifications to a file to be completed before continuing". 

13385 Issue 5 

13386 Aligned with fsync () in the POSIX Realtime Extension. Specifically, the DESCRIPTION and 

13387 RETURN VALUE sections are much expanded, and the ERRORS section is updated to indicate 

13388 that/si//ic() can return the error conditions defined for read () and ivrite (). 

13389 Issue 6 

13390 This function is marked as part of the _POSIX_FSYNC option. 

13391 The following new requirements on POSIX implementations derive from alignment with the 

13392 Single UNIX Specification: 

13393 • The [EINVAL] and [EIO] mandatory error conditions are added. 
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13394 NAME 

13395 ftell, ftello — return a file offset in a stream 

13396 SYNOPSIS 

13397 #include <stdio.h> 

13398 long int ftell (FILE * stream) ; 

13399 CX off_t ftello (FILE * stream); 

13400 

13401 DESCRIPTION 

13402 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

13403 conflict between the requirements described here and the ISO C standard is unintentional. This I 

13404 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

13405 The ftell () function shall obtain the current value of the file-position indicator for the stream 

13406 pointed to by stream. 

13407 cx The ftello () function is identical to ftell () except that the return value is of type off_t. 

13408 RETURN VALUE 

13409 cx Upon successful completion, ftell () and ftello () shall return the current value of the file-position 

13410 indicator for the stream measured in bytes from the beginning of the file. 

13411 cx Otherwise, ftell () and ftello () shall return -1, cast to long and off_t respectively, and set errno to 

13412 indicate the error. 

13413 ERRORS 

13414 cx The ftell () and ftello () functions shall fail if: 

13415 cx [EBADF] The file descriptor underlying stream is not an open file descriptor. 

13416 cx [EOVERFLOW] For ftell (), the current file offset cannot be represented correctly in an object of 

13417 type long. 

13418 cx [EOVERFLOW] For ftello (), the current file offset cannot be represented correctly in an object 

13419 of type off_t 

13420 cx [ESPIPE] The file descriptor underlying stream is associated with a pipe or FIFO. 

13421 The ftell () function may fail if: I 

13422 cx [ESPIPE] The file descriptor underlying stream is associated with a socket. I 

13423 EXAMPLES I 

13424 None. 

13425 APPLICATION USAGE 

13426 None. 

13427 RATIONALE 

13428 None. 

13429 FUTURE DIRECTIONS 

13430 None. 

13431 SEE ALSO 

13432 fgetpos{), fopen(), fseek{), lseek(), the System Interface Definitions volume of 

13433 IEEE Std. 1003.1-200x, <stdio.h> 
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13434 

13435 

13436 

13437 

13438 

13439 

13440 

13441 

13442 

13443 

13444 

13445 

13446 

13447 

13448 

13449 


CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The following change is incorporated for alignment with the ISO C standard: 

• The function return value is now defined in full as long int. It was previously defined as 

long. 

Issue 5 

Large File Summit extensions are added. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• Th e ftello () function is added. 

• The [EOVERFLOW] error conditions are added. 

An additional [ESPIPE] error condition is added for sockets. 
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13450 NAME 

13451 ftime — get date and time (LEGACY) 

13452 SYNOPSIS 

13453 xsi tinclude <sys/timeb . h> 

13454 int ftime (struct timeb * tp) ; 

13455 

13456 DESCRIPTION 

13457 The ftime( ) function shall set the time and millitm members of the timeb structure pointed to by 

13458 tp to contain the seconds and milliseconds portions, respectively, of the current time in seconds I 

13459 since the Epoch. The contents of the timezone and dstflag members of tp after a call to ftime () are I 

13460 unspecified. 

13461 The system clock need not have millisecond granularity. Depending on any granularity 

13462 (particularly a granularity of one) renders code non-portable. 

13463 RETURN VALUE 

13464 Upon successful completion, the ftime( ) function shall return 0; otherwise, -1 shall be returned. 

13465 ERRORS 

13466 No errors are defined. 

13467 EXAMPLES 

13468 Getting the Current Time and Date 

13469 The following example shows how to get the current system time values using the ftime() 

13470 function. The timeb structure pointed to by tp is filled with the current system time values for 

13471 time and millitm. 

13472 #include <sys/timeb . h> 

13473 struct timeb tp; 

13474 int status; 

13475 

13476 status = ftime (&tp); 

13477 APPLICATION USAGE 

13478 For applications portability, the time( ) function should be used to determine the current time 

13479 instead of ftime (). 

13480 RATIONALE 

13481 None. 

13482 FUTURE DIRECTIONS 

13483 This function may be withdrawn in a future version. 

13484 SEE ALSO 

13485 ctime( ), gettimeofdayO, time( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

13486 <sys/timeb.h> 

13487 CHANGE HISTORY 

13488 First released in Issue 4, Version 2. 

13489 Issue 5 

13490 Moved from X/OPEN UNIX extension to BASE. 

13491 Normative text previously in the APPLICATION USAGE section is moved to the 

13492 DESCRIPTION. 
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13493 

13494 

13495 

13496 

13497 


Issue 6 

This function is marked LEGACY. I 

The DESCRIPTION is updated to refer to "seconds since the Epoch" rather than "seconds since I 
00:00:00 UTC (Coordinated Universal Time), January 1 1980" for consistency with other time I 
functions. I 
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13498 NAME 

13499 ftok — generate an IPC key 

13500 SYNOPSIS 

13501 xsi #include <sys/ipc.h> 

13502 key_t ftok (const char *path, int id); 

13503 

13504 DESCRIPTION 

13505 Th e ftok () function shall return a key based on path and id that is usable in subsequent calls to 

13506 msgget( ), semget( ), and shmget( ). The application shall ensure that the path argument is the path I 

13507 name of an existing file that the process is able to stat(). I 

13508 Th e ftok ( ) function shall return the same key value for all paths that name the same file, when 

13509 called with the same id value, and return different key values when called with different id 

13510 values or with paths that name different files existing on the same file system at the same time. It 

13511 is unspecified whether ftok() shall return the same key value when called again after the file 

13512 named by path is removed and recreated with the same name. 

13513 Only the low order 8-bits of id are significant. The behavior of ftok( ) is unspecified if these bits 

13514 are 0. 

13515 RETURN VALUE 

13516 Upon successful completion , ftok() shall return a key. Otherwise, ftok( ) shall return (key_t)-l 

13517 and set errno to indicate the error. 

13518 ERRORS 

13519 The ftok ( ) function shall fail if: 

13520 [EACCES] Search permission is denied for a component of the path prefix. 

13521 [ELOOP] Too many symbolic links were encountered in resolving path. 

13522 [ENAMETOOLONG] 

13523 The length of the path argument exceeds |PATH_MAX} or a path name 

13524 component is longer than |NAME_MAX}. 

13525 [ENOENT] A component of path does not name an existing file or path is an empty string. 

13526 [ENOTDIR] A component of the path prefix is not a directory. 

13527 The ftok () function may fail if: 

13528 [ENAMETOOLONG] 

13529 Path name resolution of a symbolic link produced an intermediate result 

13530 whose length exceeds |PATH_MAX}. 

13531 EXAMPLES 

13532 Getting an IPC Key 

13533 The following example gets a unique key that can be used by the IPC functions semget(), 

13534 msgget( ), and shmget( ). The key returned by ftok () for this example is based on the ID value S 

13535 and the path name /tmp. 

13536 tinclude <sys/ipc.h> 

13537 

13538 key_t key; 

13539 char *path = "/tmp"; 

13540 int id = 'S'; 
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13541 key = ftok (path, id) ; 

13542 Saving an IPC Key 

13543 The following example gets a unique key based on the path name /tmp and the ID value a . It 

13544 also assigns the value of the resulting key to the semkey variable so that it will be available to a 

13545 later call to semget( ), msgget( ), or shmget (). 

13546 tinclude <sys/ipc.h> 

13547 

13548 key_t semkey; 

13549 if ((semkey = ftok ("/tmp", 'a')) == (key_t) -1) { 

13550 perror ("IPC error: ftok"); exit (1); 

13551 } 

13552 APPLICATION USAGE 

13553 For maximum portability, id should be a single-byte character. 

13554 RATIONALE 

13555 None. 

13556 FUTURE DIRECTIONS 

13557 None. 

13558 SEE ALSO 

13559 msgget( ), semget (), shmget{ ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

13560 <sys/ipc.h> 

13561 CHANGE HISTORY 

13562 First released in Issue 4, Version 2. 

13563 Issue 5 

13564 Moved from X/OPEN UNIX extension to BASE. 

13565 Issue 6 

13566 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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13567 

13568 

13569 

13570 

13571 

13572 

13573 

13574 

13575 

13576 

13577 
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13579 

13580 

13581 
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13584 

13585 

13586 

13587 

13588 

13589 

13590 

13591 

13592 

13593 

13594 

13595 

13596 

13597 

13598 

13599 

13600 

13601 

13602 

13603 

13604 

13605 

13606 

13607 

13608 


NAME 

ftruncate — truncate a file to a specified length 

SYNOPSIS 

#include <unistd.h> 

mfishm int ftruncate (int fildes, off_t length) ; 

DESCRIPTION 

If fildes is not a valid file descriptor open for writing, the /truncate () function shall fail. 

If fildes refers to a regular file, the /truncate{) function shall cause the size of the file to be 
truncated to length. If the size of the file previously exceeded length, the extra data shall no 
longer be available to reads on the file. If the file previously was smaller than this size, 
/truncate () shall either increase the size of the file or fail. If the file size is increased, the extended 
area shall appear as if it were zero-filled. The value of the seek pointer shall not be modified by 
a call to ftnmcate (). 

Upon successful completion, it fildes refers to a regular file, th e /truncate () function shall mark 
for update the st_ctime and st_mtime fields of the file and the S_ISUID and S_ISGID bits of the file 
mode maybe cleared. If the/truncate ( ) function is unsuccessful, the file is unaffected. 

xsi If the request would cause the file size to exceed the soft file size limit for the process, the 
request shall fail and the implementation shall generate the SIGXFSZ signal for the process. 

It fildes refers to a directory, /truncate ( ) shall fail. 

It fildes refers to any other file type, except a shared memory object, the result is unspecified. 

If at least one of _POSIX_MAPPED_FILES or _POSIX_SHARED_MEMORY_OBJECTS is defined. 

shm It fildes refers to a shared memory object, /truncate () shall set the size of the shared memory 
object to length. If the effect of /truncate () is to decrease the size of a shared memory object or 
memory mapped file and whole pages beyond the new end were previously mapped, then the 
whole pages beyond the new end shall be discarded. 

mpr If the Memory Protection option is supported, references to discarded pages shall result in the 
generation of a SIGBUS signal; otherwise, the result of such references is undefined. 

shm If the effect of /truncate {) is to increase the size of a shared memory object, it is unspecified if the 
contents of any mapped pages between the old end-of-file and the new are flushed to the 
underlying object. 

RETURN VALUE 

Upon successful completion, ftrnncate( ) shall return 0; otherwise, -1 shall be returned and errno 
set to indicate the error. 

ERRORS 

The /truncate () function shall fail if: 

[EINTR] A signal was caught during execution. 

[EINVAL] The length argument was less than 0. 

[EFBIG] or [EINVAL] 

The length argument was greater than the maximum file size. 

xsi [EFBIG] The file is a regular file and length is greater than the offset maximum 

established in the open file description associated with fildes. 
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13609 [EIO] An 1/O error occurred while reading from or writing to a file system. 

13610 [EBADF] or [EINVAL] 

13611 Th efildes argument is not a file descriptor open for writing. 

13612 [EINVAL] The fildes argument references a file that was opened without write 

13613 permission. 

13614 [EROFS] The named file resides on a read-only file system. 

13615 EXAMPLES 

13616 None. 

13617 APPLICATION USAGE 

13618 None. 

13619 RATIONALE 

13620 Th e ftruncate() function is part of the base standard as it was deemed to be more useful than I 

13621 truncate{). The truncate{ ) function is provided as an XST extension. I 

13622 FUTURE DIRECTIONS 

13623 None. 

13624 SEE ALSO 

13625 open(), truncate (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

13626 CHANGE HISTORY 

13627 First released in Issue 4, Version 2. 

13628 Issue 5 

13629 Moved from X/OPEN UNIX extension to BASE and aligned with /truncate {) in the POSIX 

13630 Realtime Extension. Specifically, the DESCRIPTION is extensively reworded and [EROFS] is 

13631 added to the list of mandatory errors that can be returned by /truncate ( ). 

13632 Large File Summit extensions are added. 

13633 Issue 6 

13634 The truncate( ) function has been split out into a separate reference page. 

13635 The /truncate () function is marked as part of the _POSIX_MAPPED_FILES or 

13636 _POSIX_SHARED_MEMORY_OBJECTS options. 

13637 The following new requirements on POSIX implementations derive from alignment with the 

13638 Single UNIX Specification: 

13639 • The DESCRIPTION is change to indicate that if the file size is changed, and if the file is a 

13640 regular file, the S_ISUID and S_ISGID bits in the file mode may be cleared. 

13641 The following changes were made to align with the IEEE P1003.1a draft standard: 

13642 • The DESCRIPTION text is updated. I 
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13643 NAME 

13644 ftrylockfile — stdio locking functions 

13645 SYNOPSIS 

13646 TSF #include <stdio.h> 

13647 int ftrylockfile (FILE * file) ; 

13648 

13649 DESCRIPTION 

13650 Refer to flockfile (). 
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13651 NAME 

13652 ftw — traverse (walk) a file tree 

13653 SYNOPSIS 

13654 xsi tinclude <ftw.h> 

13655 int ftw (const char *path, int (* fn) (const char *, 

13656 const struct stat *ptr, int flag) , int ndirs) ; 

13657 

13658 DESCRIPTION 

13659 The ftzv () function recursively descends the directory hierarchy rooted in path . For each object in 

13660 the hierarchy, ftw( ) shall call the function pointed to by fn, passing it a pointer to a null- 

13661 terminated character string containing the name of the object, a pointer to a stat structure 

13662 containing information about the object, and an integer. Possible values of the integer, defined 

13663 in the <ftw.h> header, are: 

13664 FTW_D For a directory. 

13665 FTW_DNR For a directory that cannot be read. 

13666 FTW_F For a file. 

13667 FTW_SL For a symbolic link (but see also FTW_NS below). 

13668 FTW_NS For an object other than a symbolic link on which stat( ) could not successfully be 

13669 executed. If the object is a symbolic link and stat( ) failed, it is unspecified whether 

13670 ftzv( ) passes FTW_SL or FTW_NS to the user-supplied function. 

13671 If the integer is FTW_DNR, descendants of that directory shall not be processed. If the integer is 

13672 FTW_NS, the stat structure contains undefined values. An example of an object that would 

13673 cause FTW_NS to be passed to the function pointed to by fn would be a file in a directory with 

13674 read but without execute (search) permission. 

13675 The/he () function shall visit a directory before visiting any of its descendants. 

13676 The ftw () function shall use at most one file descriptor for each level in the tree. 

13677 The argument ndirs should be in the range of 1 to |OPEN_MAX}. 

13678 The tree traversal shall continue until the tree is exhausted, an invocation of fn returns a non- 

13679 zero value, or some error, other than [EACCES], is detected within ftzv (). 

13680 The ndirs argument shall specify the maximum number of directory streams or file descriptors 

13681 or both available for use by ftzv () while traversing the tree. When ftzv () returns it shall close any 

13682 directory streams and file descriptors it uses not counting any opened by the application- 

13683 supplied fn function. 

13684 RETURN VALUE 

13685 If the tree is exhausted, ftzv () shall return 0. If the function pointed to by fn returns a non-zero 

13686 value, ftzv () shall stop its tree traversal and return whatever value was returned by the function 

13687 pointed to by fn . If/fa/) detects an error, it shall return -1 and set errno to indicate the error. 

13688 If ftw () encounters an error other than [EACCES] (see FTW_DNR and FTW_NS above), it shall 

13689 return -1 and set errno to indicate the error. The external variable errno may contain any error 

13690 value that is possible when a directory is opened or when one of the stat functions is executed on 

13691 a directory or file. 
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13692 ERRORS 

13693 The/to () function shall fail if: 


13694 

13695 

13696 

13697 

13698 

13699 

13700 

13701 

13702 


[EACCES] Search permission is denied for any component of path or read permission is 

denied for path. 

[ELOOP] Too many symbolic links were encountered. 

[ENAMETOOLONG] 

The length of the path exceeds {PATH_MAX}, or a path name component is 
longer than {NAME_MAX} while _POSIX_NO_TRUNC is in effect. 

[ENOENT] A component of path does not name an existing file or path is an empty string. 

[ENOTDIR] A component of path is not a directory. 

The/to () function may fail if: 


13703 [EINVAL] The value of the ndirs argument is invalid. 

13704 [ENAMETOOLONG] 

13705 Path name resolution of a symbolic link produced an intermediate result 

13706 whose length exceeds |PATH_MAX[. 

13707 In addition, if the function pointed to by fn encounters system errors, errno may be set 

13708 accordingly. 

13709 EXAMPLES 

13710 Walking a Directory Structure 

13711 The following example walks the current directory structure, calling the fn function for every 

13712 directory entry, to a maximum of 10 levels deep. 

13713 #include <ftw.h> 

13714 

13715 if (ftw fn, 10) != 0) { 

13716 perror ("ftw"); exit (2); 

13717 } 

13718 APPLICATION USAGE 

13719 The ftw () function may allocate dynamic storage during its operation. If/to() is forcibly 

13720 terminated, such as by longjmp () or siglongjmp () being executed by the function pointed to by fn 

13721 or an interrupt routine, ftw () does not have a chance to free that storage, so it remains 

13722 permanently allocated. A safe way to handle interrupts is to store the fact that an interrupt has 

13723 occurred, and arrange to have the function pointed to by fn return a non-zero value at its next 

13724 invocation. 

13725 RATIONALE 

13726 None. 

13727 FUTURE DIRECTIONS 

13728 None. 

13729 SEE ALSO 

13730 longjmp (), lstat( ), mallocj ), nftw{ ), opendir( ), siglongjmp(), stat( ), the System Interface Definitions 

13731 volume of IEEE Std. 1003.1-200x, <ftw.h>, <sys/stat.h> 
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13732 

13733 

13734 

13735 

13736 

13737 

13738 

13739 

13740 

13741 

13742 

13743 

13744 

13745 

13746 

13747 

13748 

13749 

13750 

13751 

13752 

13753 

13754 

13755 

13756 

13757 

13758 

13759 

13760 


CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The type of argument path is changed from char* to const char*. The argument list for fn has 
also been defined. 

In the DESCRIPTION, the words "other than [EACCES]" are added to the paragraph describing I 
termination conditions for tree traversal. I 

The following change is incorporated for alignment with the FIPS requirements: 

• In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 
name component is larger that |NAME_MAX[ is now defined as mandatory and marked as 
an extension. 

Issue 4, Version 2 

The following changes are incorporated for X/OPEN UNIX conformance: 

• The DESCRIPTION is updated to describe the use of the FTW_SL and FTW_NS values for a 
symbolic link. 

• The DESCRIPTION states that ftzv () uses at most one file descriptor for each level in the tree. 

• The DESCRIPTION constrains ndirs to the range from 1 to {OPEN_MAX}. 

• The RETURN VALUE section is updated to describe the case where/he () encounters an error 
other than [EACCES]. 

• In the ERRORS section, a second [ENAMETOOLONG] condition is defined that may report 
excessive length of an intermediate result of path name resolution of a symbolic link. 

Issue 5 

UX codings in the DESCRIPTION, RETURN VALUE, and ERRORS sections have been changed 
to EX. 


Issue 6 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 
This is since behavior may vary from one file system to another. 
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13761 NAME 

13762 funlockfile — stdio locking functions 

13763 SYNOPSIS 

13764 TSF #include <stdio.h> 

13765 void funlockfile (FILE * file) ; 

13766 

13767 DESCRIPTION 

13768 Refer to flockfile (). 
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13769 NAME 

13770 fwide — set stream orientation 

13771 SYNOPSIS 

13772 #include <stdio.h> 

13773 tinclude <wchar.h> 

13774 int fwide (FILE * stream, int mode) ; 

13775 DESCRIPTION 

13776 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

13777 conflict between the requirements described here and the ISO C standard is unintentional. This I 

13778 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

13779 Th efwide( ) function shall determine the orientation of the stream pointed to by stream. If mode is 

13780 greater than zero, the function first attempts to make the stream wide-oriented. If mode is less 

13781 than zero, the function first attempts to make the stream byte-oriented. Otherwise, mode is zero 

13782 and the function does not alter the orientation of the stream. 

13783 If the orientation of the stream has already been determ i ned, fwide () shall not change it. 

13784 Because no return value is reserved to indicate an error, an application wishing to check for error 

13785 situations should set errno to 0, then call fwide( ), then check errno, and if it is non-zero, assume 

13786 an error has occurred. 

13787 RETURN VALUE 

13788 Th efivide( ) function shall return a value greater than zero if, after the call, the stream has wide- 

13789 orientation, a value less than zero if the stream has byte-orientation, or zero if the stream has no 

13790 orientation. 

13791 ERRORS 

13792 Th efzvide( ) function may fail if: 

13793 cx [EBADF] The stream argument is not a valid stream. 

13794 EXAMPLES 

13795 None. 

13796 APPLICATION USAGE 

13797 A call to fwide () with mode set to zero can be used to determine the current orientation of a 

13798 stream. 

13799 RATIONALE 

13800 None. 

13801 FUTURE DIRECTIONS 

13802 None. 

13803 SEE ALSO 

13804 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

13805 CHANGE HISTORY 

13806 First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 

13807 (E). I 

13808 Issue 6 

13809 Extensions beyond the ISO C standard are now marked. 


430 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


fwprintf () 


13810 NAME 

13811 fwprintf, swprintf, wprintf — print formatted wide-character output 

13812 SYNOPSIS 

13813 tinclude <stdio.h> 

13814 #include <wchar.h> 

13815 int fwprintf (FILE * stream, const wchar_t * format , . . . ) ; 

13816 int swprintf(wchar_t *s, size_t n, const wchar_t * format, ...); 

13817 int wprintf (const wchar_t * format, . . . ) ; 

13818 DESCRIPTION 

13819 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

13820 conflict between the requirements described here and the ISO C standard is unintentional. This I 

13821 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

13822 Th e fwprintf ( ) function places output on the named output stream. The wprintf {) function places 

13823 output on the standard output stream stdout. The swprintf( ) function places output followed by 

13824 the null wide character in consecutive wide characters starting at *s; no more than n wide 

13825 characters are written, including a terminating null wide character, which is always added 

13826 (unless n is zero). 

13827 Each of these functions converts, formats, and prints its arguments under control of the format 

13828 wide-character string. The format is composed of zero or more directives: ordinary zvide- 

13829 characters, which are simply copied to the output stream, and conversion specifications , each of 

13830 which results in the fetching of zero or more arguments. The results are undefined if there are 

13831 insufficient arguments for th e format. If the format is exhausted while arguments remain, the 

13832 excess arguments are evaluated but are otherwise ignored. 

13833 xsi Conversions can be applied to the nth argument after the format in the argument list, rather than 

13834 to the next unused argument. In this case, the conversion wide character ' %' (see below) is 

13835 replaced by the sequence "%n$", where n is a decimal integer in the range [1,{NL_ARGMAX}], 

13836 giving the position of the argument in the argument list. This feature provides for the definition 

13837 of format wide-character strings that select arguments in an order appropriate to specific 

13838 languages (see the EXAMPLES section). 

13839 In format wide-character strings containing the "%n$" form of conversion specifications, 

13840 numbered arguments in the argument list can be referenced from the format wide-character 

13841 string as many times as required. 

13842 In format wide-character strings containing the ' %' form of conversion specifications, each 

13843 argument in the argument list is used exactly once. 

13844 All forms of the fwprintf () functions allow for the insertion of a language-dependent radix 

13845 character in the output string, output as a wide-character value. The radix character is defined in 

13846 the program's locale (category LC_NUMERIC). In the POSIX locale, or in a locale where the 

13847 radix character is not defined, the radix character defaults to a period (' .'). 

13848 xsi Each conversion specification is introduced by the ' %' wide character or by the wide-character 

13849 sequence " % n $", after which the following appear in sequence: 

13850 • Zero or mor e flags (in any order), which modify the meaning of the conversion specification. 

13851 • An optional minimum field width . If the converted value has fewer wide characters than the 

13852 field width, it shall be padded with spaces by default on the left; it shall be padded on the 

13853 right, if the left-adjustment flag ('-'), described below, is given to the field width. The field 

13854 width takes the form of an asterisk (' *'), described below, or a decimal integer. 
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• An optional precision that gives the minimum number of digits to appear for the d, i, o, u, x, 
and X conversions; the number of digits to appear after the radix character for the e, E, and / 
conversions; the maximum number of significant digits for the g and G conversions; or the 
maximum number of wide characters to be printed from a string in s conversions. The 
precision takes the form of a period (' .') followed either by an asterisk (' *'), described 
below, or an optional decimal digit string, where a null digit string is treated as 0. If a 
precision appears with any other conversion wide character, the behavior is undefined. 

• An optional / (ell) specifying that a following c conversion wide character applies to a wint_t 
argument; an optional l specifying that a following s conversion wide character applies to a 
wchar_t argument; an optional h specifying that a following d, i, o, it, x, or X conversion wide 
character applies to a type short int or type unsigned short int argument (the argument shall 
have been promoted according to the integral promotions, and its value shall be converted to 
type short int or unsigned short int before printing); an optional h specifying that a 
following n conversion wide character applies to a pointer to a type short int argument; an 
optional l (ell) specifying that a following d, i, o, u, x, or X conversion wide character applies 
to a type long int or unsigned long int argument; an optional l (ell) specifying that a 
following n conversion wide-character applies to a pointer to a type long int argument; or an 
optional L specifying that a following e, E, f, g, or G conversion wide character applies to a 
type long double argument. If an h, l, or L appears with any other conversion wide character, 
the behavior is undefined. 

• A conversion wide character that indicates the type of conversion to be applied. 

A field width, or precision, or both, may be indicated by an asterisk ('*'). In this case an 
argument of type int supplies the field width or precision. The application shall ensure that I 
arguments specifying field width, or precision, or both appear in that order before the argument, I 
if any, to be converted. A negative field width is taken as a ' - ' flag followed by a positive field I 
xsi width. A negative precision is taken as if the precision were omitted. In format wide-character 
strings containing the "%n$" form of a conversion specification, a field width or precision may 
be indicated by the sequence where m is a decimal integer in the range 

[1,|NL_ARGMAX}] giving the position in the argument list (after the format argument) of an 
integer argument containing the field width or precision, for example: 

wprintf(L"%l$d:%2$.*3$d:%4$.*3$d\n", hour, min, precision, sec); 

The format can contain either numbered argument specifications (that is, "%n$" and " *m$"), or 
unnumbered argument specifications (that is, ' %' and ' *'), but normally not both. The only 
exception to this is that "%%" can be mixed with the "%n$" form. The results of mixing 
numbered and unnumbered argument specifications in a format wide-character string are 
undefined. When numbered argument specifications are used, specifying the Nth argument 
requires that all the leading arguments, from the first to the (N-l)th, are specified in the format 
wide-character string. 

The flag wide characters and their meanings are: 

xsi ' The integer portion of the result of a decimal conversion (%/, %d, %», %/, %g, or %G) 

shall be formatted with thousands' grouping wide characters. For other conversions, 
the behavior is undefined. The non-monetary grouping wide character is used. 

- The result of the conversion shall be left-justified within the field. The conversion shall 

be right-justified if this flag is not specified. 

+ The result of a signed conversion shall always begin with a sign ('+' or '-'). The 

conversion shall begin with a sign only when a negative value is converted if this flag is 
not specified. 
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XSI 


<space> If the first wide character of a signed conversion is not a sign, or if a signed conversion 
results in no wide characters, a space shall be prefixed to the result. This means that if 
the <space> and ' +' flags both appear, the space flag shall be ignored. 

# This flag specifies that the value is to be converted to an alternative form. For o 

conversion, it increases the precision (if necessary) to force the first digit of the result to 
be 0. For x or X conversions, a non-zero result ahsll have Ox (or OX) prefixed to it. For e, 
E, f, g, or G conversions, the result shall always contain a radix character, even if no 
digits follow it. Without this flag, a radix character appears in the result of these 
conversions only if a digit follows it. For g and G conversions, trailing zeros shall not be 
removed from the result as they normally are. For other conversions, the behavior is 
undefined. 

0 For d, i, o, u, x, X, e, E,f, g, and G conversions, leading zeros (following any indication of 

sign or base) are used to pad to the field width; no space padding is performed. If the 0 
and 'flags both appear, the 0 flag shall be ignored. For d, i, o, u, x, and X 
conversions, if a precision is specified, the 0 flag shall be ignored. If the 0 and '' ' flags 
both appear, the grouping wide characters are inserted before zero padding. For other 
conversions, the behavior is undefined. 

The conversion wide characters and their meanings are: 

d, i The int argument is converted to a signed decimal in the style [-\dddd. The precision 
specifies the minimum number of digits to appear; if the value being converted can be 
represented in fewer digits, it shall be expanded with leading zeros. The default 
precision is 1. The result of converting 0 with an explicit precision of 0 is no wide 
characters. 

o The unsigned int argument is converted to unsigned octal format in the style dddd. The 

precision specifies the minimum number of digits to appear; if the value being 
converted can be represented in fewer digits, it shall be expanded with leading zeros. 
The default precision is 1. The result of converting 0 with an explicit precision of 0 is no 
wide characters. 

u The unsigned int argument is converted to unsigned decimal format in the style dddd. 

The precision specifies the minimum number of digits to appear; if the value being 
converted can be represented in fewer digits, it shall be expanded with leading zeros. 
The default precision is 1. The result of converting 0 with an explicit precision of 0 is no 
wide characters. 

x The unsigned int argument is converted to unsigned hexadecimal format in the style 

dddd; the letters " abodef" are used. The precision specifies the minimum number of 
digits to appear; if the value being converted can be represented in fewer digits, it shall 
be expanded with leading zeros. The default precision is 1. The result of converting 0 
with an explicit precision of 0 is no wide characters. 

X Behaves the same as the x conversion wide character except that letters " ABCDEF " are 

used instead of " abodef ". 

/ The double argument is converted to decimal notation in the style [~]ddd.ddd, where 

the number of digits after the radix character is equal to the precision specification. If 
the precision is missing, it is taken as 6; if the precision is explicitly 0 and no ' #' flag is 
present, no radix character appears. If a radix character appears, at least one digit 
appears before it. The value is rounded to the appropriate number of digits. 

The fwprintf () family of functions may make available wide-character string 
representations for infinity and NaN. 
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e, E The double argument is converted in the style [~]d.ddde±dd, where there is one digit 
before the radix character (which is non-zero if the argument is non-zero) and the 
number of digits after it is equal to the precision; if the precision is missing, it is taken 
as 6; if the precision is 0 and no ' #' flag is present, no radix character appears. The 
value is rounded to the appropriate number of digits. The E conversion wide character 
shall produce a number with £ instead of e introducing the exponent. The exponent 
always contains at least two digits. If the value is 0, the exponent is 0. 

xsi The fwprintf () family of functions may make available wide-character string 

representations for infinity and NaN. 

g, G The double argument is converted in the style/or e (or in the style £ in the case of a G 
conversion wide character), with the precision specifying the number of significant 
digits. If an explicit precision is 0, it is taken as 1. The style used depends on the value 
converted; style e (or E) shall be used only if the exponent resulting from such a 
conversion is less than -4 or greater than or equal to the precision. Trailing zeros are 
removed from the fractional portion of the result; a radix character appears only if it is 
followed by a digit. 

xsi The fwprintf () family of functions may make available wide-character string 

representations for infinity and NaN. 

c If no / (ell) qualifier is present, the int argument is converted to a wide character as if by 

calling the btowc( ) function and the resulting wide character is written. Otherwise, the 
wint_t argument is converted to wchar_t, and written. 

s If no l (ell) qualifier is present, the application shall ensure that the argument is a I 

pointer to a character array containing a character sequence beginning in the initial I 
shift state. Characters from the array are converted as if by repeated calls to the I 
mbrtowc() function, with the conversion state described by an mbstate_t object 
initialized to zero before the first character is converted, and written up to (but not 
including) the terminating null wide character. If the precision is specified, no more 
than that many wide characters are written. If the precision is not specified, or is 
greater than the size of the array, the application shall ensure that the array contains a I 
null wide character. I 

If an / (ell) qualifier is present, the application shall ensure that the argument is a I 
pointer to an array of type wchar_t. Wide characters from the array are written up to I 
(but not including) a terminating null wide character. If no precision is specified, or is I 
greater than the size of the array, the application shall ensure that the array contains a I 
null wide character. If a precision is specified, no more than that many wide characters I 
are written. I 

p The application shall ensure that the argument is a pointer to void. The value of the I 

pointer is converted to a sequence of printable wide characters, in an implementation- 
dependent manner. 

n The application shall ensure that the argument is a pointer to an integer into which is I 

written the number of wide characters written to the output so far by this call to one of I 
th e fwprintf ( ) functions. No argument is converted. I 

xsi C Same as Ic. 

xsi S Same as Is. 

% Output a ' %' wide character; no argument is converted. The entire conversion I 

specification shall be " % % ". I 
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13995 If a conversion specification does not match one of the above forms, the behavior is undefined. 

13996 In no case does a nonexistent or small field width cause truncation of a field; if the result of a 

13997 conversion is wider than the field width, the field is simply expanded to contain the conversion 

13998 result. Characters generated by fwprintf i ) and wprintfi ) are printed as if fputwc() had been 

13999 called. 

14000 cx The st_ctime and st_mtime fields of the file shall be marked for update between the call to a 

14001 successful execution of fwprintf () or wprintfi ) and the next successful completion of a call to 

14002 fflnsh () or fclose ( ) on the same stream, or a call to exit () or abort (). 

14003 RETURN VALUE 

14004 Upon successful completion, these functions shall return the number of wide characters 

14005 transmitted, excluding the terminating null wide character in the case of sivprintf{ ), or a negative 

14006 cx value if an output error was encountered, and set errno to indicate the error. 

14007 If n or more wide characters were requested to be written, swprintfi ) shall return a negative 

14008 cx value, and set errno to indicate the error. 

14009 ERRORS 

14010 For the conditions under which fwprintf ( ) and wprintfi ) fail and may fail, refer to fpntzvci ). 

14011 In addition, all forms of fwprintf () may fail if: 

14012 xsi [EILSEQ] A wide-character code that does not correspond to a valid character has been 

14013 detected. 

14014 xsi [EINVAL] There are insufficient arguments. 

14015 In addition, wprintfi ) and fwprintf i ) may fail if: 

14016 xsi [ENOMEM] Insufficient storage space is available. 

14017 EXAMPLES 

14018 To print the language-independent date and time format, the following statement could be used: 

14019 wprintf (format, weekday, month, day, hour, min); 

14020 For American usag e, format could be a pointer to the wide-character string: 

14021 L"%s, %s %d, %d:%.2d\n" 

14022 producing the message: 

14023 Sunday, July 3, 10:02 

14024 whereas for German usage, format could be a pointer to the wide-character string: 

14025 L"%l$s, %3$d. %2$s, %4$d:%5$.2d\n" 

14026 producing the message: 

14027 Sonntag, 3. Juli, 10:02 

14028 APPLICATION USAGE 

14029 None. 

14030 RATIONALE 

14031 None. 
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14032 FUTURE DIRECTIONS 

14033 None. 

14034 SEE ALSO 

14035 btoivc(), fputwc (), fwscanfi ), mbrtowc {), setlocale(), the System Interface Definitions volume of 

14036 IEEE Std. 1003.1-200x, <stdio.h>, <wchar.h>, the System Interface Definitions volume of I 

14037 IEEE Std. 1003.1-200x, Chapter 7, Locale I 

14038 CHANGE HISTORY 

14039 First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 

14040 (E). I 

14041 Issue 6 

14042 The Open Group corrigenda item U040/1 has been applied to the RETURN VALUE section, 

14043 describing the case if n or more wide characters are requested to be written using siuprintfi ). I 

14044 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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14045 NAME 

14046 fwrite — binary output 

14047 SYNOPSIS 

14048 tinclude <stdio.h> 

14049 size_t fwrite (const void *ptr, size_t size, size_t nitems, 

14050 FILE * stream) ; 

14051 DESCRIPTION 

14052 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

14053 conflict between the requirements described here and the ISO C standard is unintentional. This I 

14054 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

14055 The fwrite ( ) function shall write, from the array pointed to by ptr, up to nitems members whose 

14056 size is specified by size, to the stream pointed to by stream. The file-position indicator for the 

14057 stream (if defined) shall be advanced by the number of bytes successfully written. If an error 

14058 occurs, the resulting value of the file-position indicator for the stream is indeterminate. 

14059 cx The st_ctime and stjntime fields of the file shall be marked for update between the successful 

14060 execution of fwrite () and the next successful completion of a call to /flush () or /close () on the 

14061 same stream, or a call to exit () or abort (). 

14062 RETURN VALUE 

14063 Th e fwrite() function shall return the number of members successfully written, which may be 

14064 less than nitems if a write error is encountered. If size or nitems is 0 ,fwrite{) shall return 0 and the 

14065 state of the stream remains unchanged. Otherwise, if a write error occurs, the error indicator for 

14066 cx the stream shall be set, and errno shall be set to indicate the error. 

14067 ERRORS 

14068 Refer to fputc(). 

14069 EXAMPLES 

14070 None. 

14071 APPLICATION USAGE 

14072 Because of possible differences in member length and byte ordering, files written using fwrite () 

14073 are application-dependent, and possibly cannot be read using /read () by a different application 

14074 or by the same application on a different processor. 

14075 RATIONALE 

14076 None. 

14077 FUTURE DIRECTIONS 

14078 None. 

14079 SEE ALSO 

14080 / error (), /open (), printf(), pntc(), pnts(), write(), the System Interface Definitions volume of 

14081 IEEE Std. 1003.1-200x, <stdio.h> 

14082 CHANGE HISTORY 

14083 First released in Issue 1. 

14084 Derived from Issue 1 of the SVID. 

14085 Issue 4 

14086 In the DESCRIPTION, the text is changed to make it clear that the function advances the file- 

14087 position indicator by the number of bytes successfully written rather than the number of 

14088 characters, which could include multi-byte sequences. 
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14092 


The following change is incorporated for alignment with the ISO C standard: 
• The type of argument ptr is changed from void* to const void*. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 
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NAME 

fwscanf, swscanf, wscanf — convert formatted wide-character input 

SYNOPSIS 

#include <stdio.h> 

#include <wchar.h> 

int fwscanf(FILE * stream, const wchar_t * format, ... ) ; 

int swscanf(const wchar_t *s, const wchar_t * format, ... ) ; 

int wscanf(const wchar_t * format, ... ) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

Th e fwscanf () function reads from the named input stream. The wscanf( ) function reads from the 
standard input stream stdin. The swscanf () function reads from the wide-character string s. 
Each function reads wide characters, interprets them according to a format, and stores the 
results in its arguments. Each expects, as arguments, a control wide-character string format 
described below, and a set of pointer arguments indicating where the converted input should be 
stored. The result is undefined if there are insufficient arguments for the format. If the format is 
exhausted while arguments remain, the excess arguments are evaluated but are otherwise 
ignored. 

xsi Conversions can be applied to the nth argument after the format in the argument list, rather than 
to the next unused argument. In this case, the conversion wide character ' %' (see below) is 
replaced by the sequence "%n$ ", where n is a decimal integer in the range [1,|NL_ARGMAX}]. 
This feature provides for the definition of format wide-character strings that select arguments in 
an order appropriate to specific languages. In format wide-character strings containing the 
"%n$" form of conversion specifications, it is unspecified whether numbered arguments in the 
argument list can be referenced from the format wide-character string more than once. 

Th eformat can contain either form of a conversion specification—that is, ' %' or "%n$ "—but the 
two forms cannot normally be mixed within a single format wide-character string. The only 
exception to this is that " % % " or " % *" can be mixed with the " % n $" form. 

The fzvscanf( ) function in all its forms allows for detection of a language-dependent radix 
character in the input string, encoded as a wide-character value. The radix character is defined in 
the program's locale (category LC_NUMERIC). In the POSIX locale, or in a locale where the 
radix character is not defined, the radix character defaults to a period (' .'). 

Th e format is a wide-character string composed of zero or more directives. Each directive is 
composed of one of the following: one or more white-space wide characters (<space>, <tab>, 
<newline>, <vertical-tab>, or <form-feed> characters); an ordinary wide character (neither ' %' 
nor a white-space character); or a conversion specification. Each conversion specification is 
xsi introduced by a ' %' or the sequence " %n$ " after which the following appear in sequence: 

• An optional assignment-suppressing character ' *'. 

• An optional non-zero decimal integer that specifies the maximum field width. 

• An optional size modifier h, l (ell), or L indicating the size of the receiving object. The I 
application shall ensure that the conversion wide characters c, s, and ' [' are preceded by / I 
(ell) if the corresponding argument is a pointer to wchar_t rather than a pointer to a character I 
type. The application shall ensure that the conversion wide characters d, i, and n are preceded I 
by h if the corresponding argument is a pointer to short int rather than a pointer to int, or by l I 
(ell) if it is a pointer to long int. Similarly, the conversion wide characters o, n, and x shall be I 
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14140 

14141 

14142 

14143 

14144 

14145 

14146 

14147 

14148 

14149 

14150 

14151 

14152 

14153 

14154 

14155 

14156 

14157 

14158 

14159 

14160 

14161 

14162 

14163 

14164 

14165 

14166 

14167 

14168 

14169 

14170 

14171 

14172 

14173 

14174 

14175 

14176 

14177 

14178 

14179 

14180 

14181 

14182 

14183 

14184 

14185 

14186 


preceded by li if the corresponding argument is a pointer to unsigned short int rather than a I 
pointer to unsigned int, or by l (ell) if it is a pointer to unsigned long int. The conversion I 
wide characters e, f, and g shall be preceded by / (ell) if the corresponding argument is a I 
pointer to double rather than a pointer to float, or by L if it is a pointer to long double. If an 
h, l (ell), or L appears with any other conversion wide character, the behavior is undefined. 

• A conversion wide character that specifies the type of conversion to be applied. The valid 
conversion wide characters are described below. 

The fzvscanf( ) functions execute each directive of the format in turn. If a directive fails, as 
detailed below, the function shall return. Failures are described as input failures (due to the 
unavailability of input bytes) or matching failures (due to inappropriate input). 

A directive composed of one or more white-space wide characters is executed by reading input 
until no more valid input can be read, or up to the first wide character which is not a white- 
space wide character, which remains unread. 

A directive that is an ordinary wide character is executed as follows. The next wide character is 
read from the input and compared with the wide character that comprises the directive; if the 
comparison shows that they are not equivalent, the directive fails, and the differing and 
subsequent wide characters remain unread. 

A directive that is a conversion specification defines a set of matching input sequences, as 
described below for each conversion wide character. A conversion specification is executed in 
the following steps. 

Input white-space wide characters (as specified by iszvspace( )) are skipped, unless the conversion 
specification includes a ' [', c, or n conversion character. 

An item is read from the input, unless the conversion specification includes an n conversion 
wide character. An input item is defined as the longest sequence of input wide characters, not 
exceeding any specified field width, which is an initial subsequence of a matching sequence. The 
first wide character, if any, after the input item remains unread. If the length of the input item is 
0, the execution of the conversion specification fails; this condition is a matching failure, unless 
end-of-file, an encoding error, or a read error prevented input from the stream, in which case it is 
an input failure. 

Except in the case of a ' %' conversion wide character, the input item (or, in the case of a %n 
conversion specification, the count of input wide characters) is converted to a type appropriate 
to the conversion wide character. If the input item is not a matching sequence, the execution of 
the conversion specification fails; this condition is a matching failure. Unless assignment 
suppression was indicated by a ' *', the result of the conversion is placed in the object pointed 
to by the first argument following the format argument that has not already received a 
xsi conversion result if the conversion specification is introduced by ' %', or in the nth argument if 

introduced by the wide-character sequence "%n$". If this object does not have an appropriate 
type, or if the result of the conversion cannot be represented in the space provided, the behavior 
is undefined. 

The following conversion wide characters are valid: 

d Matches an optionally signed decimal integer, whose format is the same as expected for 

the subject sequence of zvcstol() with the value 10 for the base argument. In the absence I 
of a size modifier, the application shall ensure that the corresponding argument is a I 
pointer to int. I 

i Matches an optionally signed integer, whose format is the same as expected for the 

subject sequence of zvcstol() with 0 for the base argument. In the absence of a size I 
modifier, the application shall ensure that the corresponding argument is a pointer to I 
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14187 


int. 

14188 

14189 

14190 

14191 

0 

Matches an optionally signed octal integer, whose format is the same as expected for 
the subject sequence of wcstoul () with the value 8 for the base argument. In the absence 
of a size modifier, the application shall ensure that the corresponding argument is a 
pointer to unsigned int. 

14192 

14193 

14194 

14195 

U 

Matches an optionally signed decimal integer, whose format is the same as expected for 
the subject sequence of wcstoul () with the value 10 for the base argument. In the absence 
of a size modifier, the application shall ensure that the corresponding argument is a 
pointer to unsigned int. 

14196 

14197 

14198 

14199 

X 

Matches an optionally signed hexadecimal integer, whose format is the same as 
expected for the subject sequence of wcstonl{) with the value 16 for the base argument. 
In the absence of a size modifier, the application shall ensure that the corresponding 
argument is a pointer to unsigned int. 

14200 

14201 

14202 

e ’f’g 

Matches an optionally signed floating-point number, whose format is the same as 
expected for the subject sequence of wcstod(). In the absence of a size modifier, the 
application shall ensure that the corresponding argument is a pointer to float. 

14203 

14204 

14205 

14206 


If the fwprintfi ) family of functions generates character string representations for 
infinity and NaN (a 7 858 symbolic entity encoded in floating-point format) to support 
the IEEE Std. 754:1985 standard, the fwscanf ( ) family of functions shall recognize them 
as input. 

14207 

14208 

14209 

14210 

14211 

14212 

S 

Matches a sequence of non white-space wide characters. If no l (ell) qualifier is present, 
characters from the input field are converted as if by repeated calls to the wcrtomb() 
function, with the conversion state described by an mbstate_t object initialized to zero 
before the first wide character is converted. The application shall ensure that the 
corresponding argument is a pointer to a character array large enough to accept the 
sequence and the terminating null character, which shall be added automatically. 

14213 

14214 

14215 


Otherwise, the application shall ensure that the corresponding argument is a pointer to 
an array of wchar_t large enough to accept the sequence and the terminating null wide 
character, which shall be added automatically. 

14216 

14217 

14218 

14219 

14220 

14221 

14222 

[ 

Matches a non-empty sequence of wide characters from a set of expected wide 
characters (the scanset). If no l (ell) qualifier is present, wide characters from the input 
field are converted as if by repeated calls to the ivcrtomb( ) function, with the conversion 
state described by an mbstate_t object initialized to zero before the first wide character 
is converted. The application shall ensure that the corresponding argument is a pointer 
to a character array large enough to accept the sequence and the terminating null 
character, which shall be added automatically. 

14223 

14224 

14225 


If an l (ell) qualifier is present, the application shall ensure that the corresponding 
argument is a pointer to an array of wchar_t large enough to accept the sequence and 
the terminating null wide character, which shall be added automatically. 

14226 

14227 

14228 

14229 

14230 

14231 

14232 

14233 


The conversion specification includes all subsequent wide characters in the format 
string up to and including the matching right square bracket (']')• The wide 
characters between the square brackets (the scanlist) comprise the scanset, unless the 
wide character after the left square bracket is a circumflex (' ''), in which case the 
scanset contains all wide characters that do not appear in the scanlist between the 
circumflex and the right square bracket. If the conversion specification begins with 
" [ ] " or " [" ] ", the right square bracket is included in the scanlist and the next right 
square bracket is the matching right square bracket that ends the conversion 
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specification; otherwise, the first right square bracket is the one that ends the 
conversion specification. If a ' —' is in the scanlist and is not the first wide character, 
nor the second where the first wide character is a ' "', nor the last wide character, the 
behavior is implementation-dependent. 

c Matches a sequence of wide characters of the number specified by the field width (1 if 

no field width is present in the conversion specification). If no / (ell) qualifier is present, 
wide characters from the input field are converted as if by repeated calls to the 
wcrtomb() function, with the conversion state described by an mbstate_t object 
initialized to zero before the first wide character is converted. The application shall I 
ensure that the corresponding argument is a pointer to a character array large enough I 
to accept the sequence. No null character is added. I 

Otherwise, the application shall ensure that the corresponding argument is a pointer to I 
an array of wchar_t large enough to accept the sequence. No null wide character is I 
added. 

p Matches an implementation-dependent set of sequences, which shall be the same as the I 

set of sequences that is produced by the %p conversion of the corresponding fivprintf( ) I 

functions. The application shall ensure that the corresponding argument is a pointer to I 
a pointer to void. The interpretation of the input item is implementation-dependent. If I 
the input item is a value converted earlier during the same program execution, the 
pointer that results shall compare equal to that value; otherwise, the behavior of the %p 
conversion is undefined. 

n No input is consumed. The application shall ensure that the corresponding argument is I 

a pointer to the integer into which is to be written the number of wide characters read I 
from the input so far by this call to the ftvscanf() functions. Execution of a %n I 

conversion specification does not increment the assignment count returned at the 
completion of execution of the function. 

xsi C Same as Ic. 

5 Same as Is. 

% Matches a single ' %'; no conversion or assignment occurs. The complete conversion I 

specification shall be " % % ". I 

If a conversion specification is invalid, the behavior is undefined. 

The conversion characters E, G, and X are also valid and behave the same as, respectively, e, g, 
and x. 

If end-of-file is encountered during input, conversion is terminated. If end-of-file occurs before 
any wide characters matching the current conversion specification (except for %n) have been 
read (other than leading white-space, where permitted), execution of the current conversion 
specification terminates with an input failure. Otherwise, unless execution of the current 
conversion specification is terminated with a matching failure, execution of the following 
conversion specification (if any) is terminated with an input failure. 

Reaching the end of the string in szvscanf( ) is equivalent to encountering end-of-file for fzvscanf( ). 

If conversion terminates on a conflicting input, the offending input is left unread in the input. 
Any trailing white space (including <newline>) is left unread unless matched by a conversion 
specification. The success of literal matches and suppressed assignments is only directly 
determinable via the %n conversion specification. 

The fzvscanf( ) and zvscanf( ) functions may mark the st_atime field of the file associated with 
stream for update. The st_atime field shall be marked for update by the first successful execution 
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14280 of fgetc (), fgetzvc (), _/ 'gets (), fgetzvs (), fread (), getc (), getzvc (), getchar (), getzvchar (), gets (), fscanf{ ), 

14281 or fzvscanf( ) using stream that returns data not supplied by a prior call to nngetc( ). 

14282 RETURN VALUE 

14283 Upon successful completion, these functions shall return the number of successfully matched 

14284 and assigned input items; this number can be 0 in the event of an early matching failure. If the 

14285 input ends before the first matching failure or conversion, EOF shall be returned. If a read error 

14286 cx occurs the error indicator for the stream is set, EOF shall be returned, and errno shall be set to 

14287 indicate the error. 

14288 ERRORS 

14289 For the conditions under which th efzvscanf( ) functions shall fail and may fail, refer to fgetzvc (). 

14290 In addition, fzvscanf( ) may fail if: 

14291 xsi [EILSEQ] Input byte sequence does not form a valid character. 

14292 xsi [EINVAL] There are insufficient arguments. 

14293 EXAMPLES 

14294 The call: 

14295 int i, n; float x; char name [50]; 

14296 n = wscanf (L"%d%f%s", &i, &x, name); 

14297 with the input line: 

14298 2 5 5 4.32E—1 Hamster 

14299 assigns to n the value 3, to i the value 25, to x the value 5.432, and name contains the string 

14300 "Hamster". 

14301 The call: 

14302 int i; float x; char name [50]; 

14303 (void) wscanf (L"%2d%f%*d %[ 012345 678 9 ]" , &i, &x, name); 

14304 with input: 

14305 5 6 7 8 9 0 1 2 3 5 6 a72 

14306 assigns 56 to i, 789.0 to x, skip 0123, and place the string "56\0" in name. The next call to 

14307 getchar () shall return the character ' a'. 

14308 APPLICATION USAGE 

14309 In format strings containing the ' %' form of conversion specifications, each argument in the 

14310 argument list is used exactly once. 

14311 RATIONALE 

14312 None. 

14313 FUTURE DIRECTIONS 

14314 None. 

14315 SEE ALSO 

14316 getzvc (), fzvprintfO, setlocale{), zvcstod(), zvcstol(), zvcstoul(), zvcrtomb(), the System Interface 

14317 Definitions volume of IEEE Std. 1003.1-200x, <langinfo.h>, <stdio.h>, <wchar.h>, the System I 

14318 Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale I 
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14319 

14320 

14321 

14322 

14323 


CHANGE HISTORY 

First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 
(E). I 

Issue 6 I 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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14324 NAME 

14325 gai_strerror — address and name information error description 

14326 SYNOPSIS 

14327 #include <netdb.h> 

14328 char *gai_strerror (int ecode) ; 

14329 DESCRIPTION 

14330 The gai_strerror() function shall return a text string describing an error that is listed in the 

14331 <netdb.h> header. 

14332 When the ecode argument is one of the values listed in the <netdb.h> header, the function return 

14333 value points to a string describing the error. If the argument is not one of those values, the 

14334 function shall return a pointer to a string whose contents indicate an unknown error. 

14335 RETURN VALUE 

14336 Upon successful completion, gai_strerror() shall return a pointer to an implementation- 

14337 dependent string. 

14338 ERRORS 

14339 No errors are defined. 

14340 EXAMPLES 

14341 None. 

14342 APPLICATION USAGE 

14343 None. 

14344 RATIONALE 

14345 None. 

14346 FUTURE DIRECTIONS 

14347 None. 

14348 SEE ALSO 

14349 getaddrinfo(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <netdb.h> 

14350 CHANGE HISTORY 

14351 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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14352 NAME 

14353 gcvt — convert a floating-point number to a string (LEGACY) 

14354 SYNOPSIS 

14355 xsi tinclude <stdlib.h> 

14356 char *gcvt (double value, int ndigit, char *buf) ; 

14357 

14358 DESCRIPTION 

14359 Refer to ecvt (). 
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14360 NAME 

14361 getaddrinfo — get address information 

14362 SYNOPSIS 

14363 tinclude <sys/socket. h> 

14364 #include <netdb.h> 

14365 int getaddrinfo (const char * nodename, const char *servname, 

14366 const struct addrinfo *hints, struct addrinfo **res) ; 

14367 DESCRIPTION 

14368 Refer to freeaddrinfo () . 


System Interfaces, Issue 6 


447 




getc() 


System Interfaces 


14369 

14370 

14371 

14372 

14373 

14374 

14375 

14376 

14377 

14378 

14379 

14380 

14381 

14382 

14383 

14384 

14385 

14386 

14387 

14388 

14389 

14390 

14391 

14392 

14393 

14394 

14395 

14396 

14397 

14398 

14399 

14400 

14401 

14402 

14403 

14404 

14405 

14406 


NAME 

getc — get a byte from a stream 

SYNOPSIS 

#include <stdio.h> 
int getc(FILE * stream); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The getc {) function shall be equivalent to fgetc (), except that if it is implemented as a macro it 
may evaluate stream more than once, so the argument should never be an expression with side 
effects. 

RETURN VALUE 

Refer to fgetc(). 

ERRORS 

Refer to fget c (). 

EXAMPLES 

None. 

APPLICATION USAGE 

If the integer value returned by getc () is stored into a variable of type char and then compared 
against the integer constant EOF, the comparison may never succeed, because sign-extension of 
a variable of type char on widening to integer is implementation-dependent. 

Because it may be implemented as a macro, getc () may treat incorrectly a stream argument with 
side effects. In particular, getc(*f++) does not necessarily work as expected. Therefore, use of this 
function should be preceded by "#undef getc" in such situations;/yefc() could also be used. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

fgetc (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdio.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The words "a character variable" are replaced by "a variable of type char", to emphasize the fact 
that this function deals with byte values. 

The APPLICATION USAGE section now states that the use of this function is not recommended. 
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14407 NAME 

14408 getc_unlocked, getchar_imlocked, putc_unlocked, putchar_unlocked — stdio with explicit client 

14409 locking 

14410 SYNOPSIS 

14411 tsf #include <stdio.h> 

14412 

14413 

14414 

14415 

14416 

14417 DESCRIPTION 

14418 Versions of the functions getc(), getchar(), pntc(), and putchar() respectively named 

14419 getc_unlocked(), getchar_anlocked(), pntc_iinlocked(), and putchar_unlocked() shall be provided 

14420 which are functionally identical to the original versions, with the exception that they are not 

14421 required to be implemented in a thread-safe manner. They may only safely be used within a 

14422 scope protected by flockfile () (or ftrylockfile ()) and funlockfile( ). These functions may safely be 

14423 used in a multi-threaded program if and only if they are called while the invoking thread owns 

14424 the (FILE 51 ') object, as is the case after a successful call of the flockfile ( ) or ftrylockfile ( ) functions. 

14425 RETURN VALUE 

14426 See getc (), getchar (), putc( ), and putchar{ ). 

14427 ERRORS 

14428 No errors are defined. 

14429 EXAMPLES 

14430 None. 

14431 APPLICATION USAGE 

14432 Because they may be implemented as macros, getc_nnlocked() and putc_nnlocked{ ) may treat 

14433 incorrectly a stream argument with side effects. In particular, getc_nnlocked(* f++) and 

14434 pntc_iinlocked(*i++) do not necessarily work as expected. Therefore, use of these functions in 

14435 such situations should be preceded by the following statement as appropriate: 

14436 #undef getc_unlocked 

14437 #undef putc_unlocked 

14438 RATIONALE 

14439 Some I/O functions are typically implemented as macros for performance reasons (for example, 

14440 pntc{) and getc()). For safety, they need to be synchronized, but it is often too expensive to 

14441 synchronize on every character. Nevertheless, it was felt that the safety concerns were more 

14442 important; consequently, the getc( ), getchar( ), pntc( ), and pntchar( ) functions are required to be 

14443 thread-safe. However, unlocked versions are also provided with names that clearly indicate the 

14444 unsafe nature of their operation but can be used to exploit their higher performance. These 

14445 unlocked versions can be safely used only within explicitly locked program regions, using 

14446 exported locking primitives. In particular, a sequence such as: 

14447 flockfile (fileptr) ; 

14448 putc_unlocked (' 1' , fileptr); 

14449 putc_unlocked (' \n' , fileptr); 

14450 fprintf (fileptr, "Line 2\n"); 

14451 funlockfile (fileptr) ; 

14452 is permissible, and results in the text sequence: 


int getc_unlocked(FILE * stream); 
int getchar_unlocked(void) ; 
int putc_unlocked(int c, FILE * stream); 
int putchar_unlocked(int c) ; 
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14453 1 

14454 Line 2 

14455 being printed without being interspersed with output from other threads. 

14456 It would be wrong to have the standard names such as getc(), pntc{), and so on, map to the 

14457 "faster, but unsafe" rather than the "slower, but safe" versions. In either case, you would still 

14458 want to inspect all uses of getc(), pntc(), and so on, by hand when converting existing code. 

14459 Choosing the safe bindings as the default, at least, results in correct code and maintains the 

14460 "atomicity at the function" invariant. To do otherwise would introduce gratuitous 

14461 synchronization errors into converted code. Other routines that modify the stdio (FILE*) 

14462 structures or buffers are also safely synchronized. 

14463 Note that there is no need for functions of the form getcjocked (), putcjocked (), and so on, since 

14464 this is the functionality of getc(), pntc{), et at. It would be inappropriate to use a feature test 

14465 macro to switch a macro definition of getc( ) between getcjocked ( ) and getc_nnlocked( ), since the 

14466 ISO C standard requires an actual function to exist, a function whose behavior could not be 

14467 changed by the feature test macro. Also, providing both the xxxjocked () and xxx_nnlocked() 

14468 forms leads to the confusion of whether the suffix describes the behavior of the function or the 

14469 circumstances under which it should be used. 

14470 Three additional routines, flockfile (), ftrylockfile (), and funlockfile() (which may be macros), are 

14471 provided to allow the user to delineate a sequence of I/O statements that are executed I 

14472 synchronously. I 

14473 The ungetc () function is infrequently called relative to the other functions/macros so no 

14474 unlocked variation is needed. 

14475 FUTURE DIRECTIONS 

14476 None. 

14477 SEE ALSO 

14478 yefc(), getchar(), pntc{), putchar{), the System Interface Definitions volume of 

14479 IEEE Std. 1003.1-200x, <stdio.h> 

14480 CHANGE HISTORY 

14481 First released in Issue 5. Included for alignment with the POSIX Threads Extension. I 

14482 Issue 6 

14483 These functions are marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS option. 

14484 The Open Group corrigenda item U030/2 has been applied adding APPLICATION USAGE 

14485 describing how applications should be written to avoid the case when the functions are 

14486 implemented as macros. 
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14487 

14488 

14489 

14490 

14491 

14492 

14493 

14494 

14495 

14496 

14497 

14498 

14499 

14500 

14501 

14502 

14503 

14504 

14505 

14506 

14507 

14508 

14509 

14510 

14511 

14512 

14513 

14514 

14515 

14516 

14517 

14518 

14519 

14520 


NAME 

getchar — get a byte from a stdin stream 

SYNOPSIS 

#include <stdio.h> 
int getchar(void) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The getchar () function shall be equivalent to getc(stdin). 

RETURN VALUE 

Refer to fgetc(). 

ERRORS 

Refer to fgetc (). 

EXAMPLES 

None. 

APPLICATION USAGE 

If the integer value returned by getchar () is stored into a variable of type char and then 
compared against the integer constant EOF, the comparison may never succeed, because sign- 
extension of a variable of type char on widening to integer is implementation-dependent. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

getc (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdio.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The words "a character variable" are replaced by "a variable of type char", to emphasize the fact 
that this function deals in byte values. 

The following change is incorporated for alignment with the ISO C standard: 

• The argument list is explicitly defined as void. 
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14558 

14559 

14560 
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14562 
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NAME 

getcontext, setcontext — get and set current user context 

SYNOPSIS 

xsi tinclude <ucontext.h> 

int getcontext(ucontext_t *ucp ); 

int setcontext (const ucontext_t *ucp); 


DESCRIPTION 

The getcontext () function shall initialize the structure pointed to by ucp to the current user 
context of the calling thread. The ucontext_t type that ucp points to defines the user context and 
includes the contents of the calling thread's machine registers, the signal mask, and the current 
execution stack. 

The setcontext () function shall restore the user context pointed to by ucp. A successful call to 
setcontext() shall not return; program execution resumes at the point specified by the ucp 
argument passed to setcontext (). The ucp argument should be created either by a prior call to 
getcontext () or makecontext() r or by being passed as an argument to a signal handler. If the ucp 
argument was created with getcontext (), program execution continues as if the corresponding 
call of getcontext () had just returned. If the ucp argument was created with makecontext(), 
program execution continues with the function passed to makecontext(). When that function 
returns, the thread shall continue as if after a call to setcontext( ) with the ucp argument that was 
input to makecontext(). If the ucjink member of the ucontext_t structure pointed to by the ucp 
argument is equal to 0, then this context is the main context, and the thread shall exit when this 
context returns. The effects of passing a ucp argument obtained from any other source are 
unspecified. 

RETURN VALUE 

Upon successful completion, setcontext () shall not return and getcontext () shall return 0; 
otherwise, a value of -1 shall be returned. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

When a signal handler is executed, the current user context is saved and a new context is 
created. If the thread leaves the signal handler via longjmp(), then it is unspecified whether the 
context at the time of the corresponding setjmp () call is restored and thus whether future calls to 
getcontext () provide an accurate representation of the current context, since the context restored 
by longjmp () does not necessarily contain all the information that setcontext () requires. Signal 
handlers should use siglongjmp() or setcontext () instead. 

Portable applications should not modify or access the uc_mcontext member of ucontext_t. A 
portable application cannot assume that context includes any process-wide static data, possibly 
including errno. Users manipulating contexts should take care to handle these explicitly when 
required. 

Use of contexts to create alternate stacks is not defined by this volume of IEEE Std. 1003.1-200x. 
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14564 RATIONALE 

14565 None. 

14566 FUTURE DIRECTIONS 

14567 None. 

14568 SEE ALSO 

14569 bsd_signal (), makecontext ( ), setjmp (), sigaction (), sigaltstack (), sigprocmask (), sigsetjmp (), the 

14570 System Interface Definitions volume of IEEE Std. 1003.1-200x, <ucontext.h> 

14571 CHANGE HISTORY 

14572 First released in Issue 4, Version 2. 

14573 Issue 5 

14574 Moved from X/OPEN UNIX extension to BASE. 

14575 The following sentence was removed from the DESCRIPTION: "If the ncp argument was passed 

14576 to a signal handler, program execution continues with the program instruction following the 

14577 instruction interrupted by the signal." 
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14578 

14579 

14580 

14581 

14582 

14583 

14584 

14585 

14586 

14587 

14588 

14589 

14590 

14591 

14592 

14593 

14594 

14595 

14596 

14597 

14598 

14599 

14600 

14601 

14602 

14603 

14604 

14605 

14606 

14607 

14608 

14609 

14610 

14611 

14612 

14613 

14614 

14615 

14616 

14617 

14618 


NAME 

getcwd — get the path name of the current working directory 

SYNOPSIS 

#include <unistd.h> 

char *getcwd(char *buf, size_t size); 

DESCRIPTION 

The getcivd() function shall place an absolute path name of the current working directory in the 
array pointed to by buf, and return buf. The path name copied to the array shall contain no I 
components that are symbolic links. The size argument is the size in bytes of the character array I 
pointed to by the buf argument. If buf is a null pointer, the behavior of getcwd () is undefined. 

RETURN VALUE 

Upon successful completion, getcwd() shall return the buf argument. Otherwise, getczud () shall 
return a null pointer and set errno to indicate the error. The contents of the array pointed to by 
buf are then undefined. 

ERRORS 

The getcivd() function shall fail if: 

[EINVAL] The size argument is 0. 

[ERANGE] The size argument is greater than 0, but is smaller than the length of the path 

name +1. 

The getczvd( ) function may fail if: 

[EACCES] Read or search permission was denied for a component of the path name. 

man [ENOMEM] Insufficient storage space is available. 

EXAMPLES 

Determining the Absolute Path Name of the Current Working Directory 

The following example returns a pointer to an array that holds the absolute path name of the 
current working directory. The pointer is returned in the ptr variable, which points to the buf 
array where the path name is stored. 

#include <stdlib.h> 

#include <unistd.h> 

long size; 
char *buf; 
char *ptr; 

size = pathconf(".", _PC_PATH_MAX); 

if ((buf = (char*)malloc((size_t)size)) != NULL) 

ptr = getcwd (buf, (size_t)size); 

APPLICATION USAGE 

If buf is a null pointer, getcwd () may obtain size bytes of memory using malloc (). In this case, the 
pointer returned by getcwd{) may be used as the argument in a subsequent call to free(). 
Invoking getczud () with buf as a null pointer is not recommended. 
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14619 RATIONALE 

14620 Since the maximum path name length is arbitrary unless |PATH_MAX} is defined, an 

14621 application generally cannot supply a buf with size |{PATH_MAX} +1}. 

14622 Having getciud () take no arguments and instead use the tnalloc () function to produce space for 

14623 the returned argument was considered. The advantage is that getczud() knows how big the 

14624 working directory path name is and can allocate an appropriate amount of space. But the 

14625 programmer would have to use the free( ) function to free the resulting object, or each use of 

14626 getczvd( ) would further reduce the available memory. Also, malloc() and free( ) are used nowhere 

14627 else in this volume of IEEE Std. 1003.1-200x. Finally, getczud () is taken from the SVID where it 

14628 has the two arguments used in this volume of IEEE Std. 1003.1-200x. 

14629 The older function getzud() was rejected for use in this context because it had only a buffer 

14630 argument and no size argument, and thus had no way to prevent overwriting the buffer, except 

14631 to depend on the programmer to provide a large enough buffer. 

14632 The result if a NULL argument is passed to getczvd( ) is left implementation-dependent because 

14633 some implementations dynamically allocate space in that case. 

14634 If a program is operating in a directory where some (grand)parent directory does not permit 

14635 reading, getczud () may fail, as in most implementations it must read the directory to determine 

14636 the name of the file. This can occur if search, but not read, permission is granted in an 

14637 intermediate directory, or if the program is placed in that directory by some more privileged 

14638 process (for example, login). Including the [EACCES] error condition makes the reporting of the I 

14639 error consistent and warns the application writer that getczud () can fail for reasons beyond the 

14640 control of the application writer or user. Some implementations can avoid this occurrence (for 

14641 example, by implementing getczud () using pzud, where pzud is a set-user-root process), thus the 

14642 error was made optional. 

14643 Because this volume of IEEE Std. 1003.1-200x permits the addition of other errors, this would be 

14644 a common addition and yet one that applications could not be expected to deal with without 

14645 this addition. 

14646 FUTURE DIRECTIONS 

14647 None. 

14648 SEE ALSO 

14649 maUoc(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

14650 CHANGE HISTORY 

14651 First released in Issue 1. 

14652 Derived from Issue 1 of the SVID. 

14653 Issue 4 

14654 The <unistd.h> header is added to the SYNOPSIS section. 

14655 The [ENOMEM] error is marked as an extension. 

14656 The words "as this functionality may be subject to withdrawal" have been deleted from the end 

14657 of the last sentence in the APPLICATION USAGE section. 

14658 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

14659 • The DESCRIPTION is changed to indicate that the effects of passing a null pointer in buf are 

14660 undefined. 
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14661 

14662 

14663 

14664 


Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The [ENOMEM] optional error condition is added. 
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14665 NAME 

14666 getdate — convert user format date and time 

14667 SYNOPSIS 

14668 xsi #include <time.h> 

14669 struct tm *getdate (const char * string) ; 

14670 

14671 DESCRIPTION 

14672 The getdate () function shall convert a string representation of a date or time into a broken-down 

14673 time. 

14674 The external variable or macro getdate_err is used by getdate () to return error values. 

14675 Templates are used to parse and interpret the input string. The templates are contained in a text 

14676 file identified by the environment variable DATEMSK. The DATEMSK variable should be set to 

14677 indicate the full path name of the file that contains the templates. The first line in the template 

14678 that matches the input specification is used for interpretation and conversion into the internal 

14679 time format. 

14680 The following field descriptors are supported: 


14681 

"o "O 

Same as ' %'. 

14682 

%a 

Abbreviated weekday name. 

14683 

%A 

Full weekday name. 

14684 

%b 

Abbreviated month name. 

14685 

%B 

Full month name. 

14686 

%c 

Locale's appropriate date and time representation. 

14687 

%C 

Century number (00-99; leading zeros are permitted but not required). 

14688 

%d 

Day of month (01-31; the leading 0 is optional). 

14689 

%D 

Date as %m/%d/%y. 

14690 

%e 

Same as %d. 

14691 

%h 

Abbreviated month name. 

14692 

%H 

Hour (00-23). 

14693 

%I 

Hour (01-12). 

14694 

%m 

Month number (01-12). 

14695 

%M 

Minute (00-59). 

14696 

%n 

Same as <newline>. 

14697 

%p 

Locale's equivalent of either AM or PM. 

14698 

14699 

%r 

The locale's appropriate representation of time in AM and PM notation. In the POSIX 
locale, this is equivalent to %J:%M:%S %p. 

14700 

%R 

Time as %H:%M. 

14701 

14702 

%S 

Seconds (00-61). Leap seconds are allowed but are not predictable through use of 
algorithms. 
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14703 

14704 

14705 

14706 

14707 

14708 

14709 

14710 

14711 

14712 

14713 

14714 

14715 

14716 

14717 

14718 

14719 

14720 

14721 

14722 

14723 

14724 

14725 

14726 

14727 

14728 

14729 

14730 

14731 

14732 

14733 

14734 

14735 

14736 

14737 

14738 

14739 

14740 

14741 
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%t 

Same as <tab>. 

%T 

Time as %H:%M:%S. 

%iv 

Weekday number (Sunday = 0-6). 

%x 

Locale's appropriate date representation. 

%X 

Locale's appropriate time representation. 

%y 

Year within century. When a century is not otherwise specified, values in the range 
69-99 refer to years in the twentieth century (1969 to 1999 inclusive); values in the range 
00-68 refer to years in the twenty-first century (2000 to 2068 inclusive). 

%Y 

Year as ccyy (for example, 1994). 

%Z 

Timezone name or no characters if no timezone exists. If the timezone supplied by %Z 
is not the timezone that getdate() expects, an invalid input specification error shall 
result. The get date () function calculates an expected timezone based on information 
supplied to the function (such as the hour, day, and month). 


The match between the template and input specification performed by get date () is case- 
insensitive. 


The month and weekday names can consist of any combination of upper and lowercase letters. 
The process can request that the input date or time specification be in a specific language by 
setting the LC_TIME category (see setlocale ()). 

Leading 0s are not necessary for the descriptors that allow leading 0s. However, at most two 
digits are allowed for those descriptors, including leading 0s. Extra whitespace in either the 
template file or in string is ignored. 

The field descriptors %c, %x, and %X shall not be supported if they include unsupported field 
descriptors. 

The following rules apply for converting the input specification into the internal format: 

• If %Z is being scanned, then get date () initializes the broken-down time to be the current time 
in the scanned timezone. Otherwise, it initializes the broken-down time based on the current 
local time as if localtime () had been called. 

• If only the weekday is given, today is assumed if the given day is equal to the current day 
and next week if it is less, 

• If only the month is given, the current month is assumed if the given month is equal to the 
current month and next year if it is less, and no year is given (the first day of month is 
assumed if no day is given), 

• If no hour, minute, and second are given the current hour, minute, and second are assumed, 

• If no date is given, today is assumed if the given hour is greater than the current hour and 
tomorrow is assumed if it is less. 

If a field descriptor specification in the DATEMSK file does not correspond to one of the field 
descriptors above, the behavior is unspecified. 

The getdate( ) function need not be reentrant. A function that is not required to be reentrant is not 
required to be thread-safe. 
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14742 RETURN VALUE 

14743 Upon successful completion, get date () shall return a pointer to a struct tm. Otherwise, it shall 

14744 return a null pointer and set getdate_err to indicate the error. 


14745 ERRORS 

14746 The getdate () function shall fail in the following cases, setting getdate_err to the value shown in 

14747 the list below. Any changes to errno are unspecified. 


14748 1. 

14749 2. 

14750 3. 

14751 4. 

14752 5. 

14753 6. 

14754 7. 

14755 8. 

14756 

14757 EXAMPLES 

14758 1. 


14759 

14760 

14761 

14762 

14763 

14764 

14765 

14766 

14767 

14768 2. 

14769 

14770 

14771 

14772 

14773 

14774 

14775 

14776 

14777 

14778 3. 

14779 


The DATEMSK environment variable is null or undefined. 

The template file cannot be opened for reading. 

Failed to get file status information. 

The template file is not a regular file. 

An I/O error is encountered while reading the template file. 

Memory allocation failed (not enough memory available). 

There is no line in the template that matches the input. 

Invalid input specification. For example, February 31; or a time is specified that cannot be 
represented in a time_t (representing the time in seconds since the Epoch). 


The following example shows the possible contents of a template: 

%m 

%A %B %d, % Y, %H:%M:%S 

%A 

%B 

%m/%d/%y %I %p 

-sd, -sm, -sY 'sHi'slM 

at %A the %dst of %B in %Y 

run job at %I %p,%B %dnd 

%A den %d. %B %Y %H.%M Uhr 

The following are examples of valid input specifications for the template in Example 1: 

getdate("10/1/87 4 PM"); 
getdate("Friday") ; 

getdate("Friday September 18, 1987, 10:30:30"); 

getdate("24,9, 1986 10:30"); 

getdate("at monday the 1st of december in 1986"); 
getdate("run job at 3 PM, december 2nd"); 

If the LC_TIME category is set to a German locale that includes freitag as a weekday name 
and oktober as a month name, the following would be valid: 

getdate("freitag den 10. oktober 1986 10.30 Uhr"); 

The following example shows how local date and time specification can be defined in the 
template: 
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14780 


14781 

Invocation 

Line in Template 

14782 

getdate("11/27/86") 

%m/%d/%y 

14783 

getdate("27.11.86") 

%d.%m.%y 

14784 

getdate("86-11-27") 

%y-%m-%d 

14785 

getdate("Friday 12:00:00") 

%A %H:%M:%S 


14786 4. The following examples help to illustrate the above rules assuming that the current date is 

14787 Mon Sep 22 12:19:47 EDT 1986 and the LCJTIME category is set to the default C locale: 

14788 


14789 

Input 

Line in Template 

Date 

14790 

Mon 

% cl 

Mon Sep 22 12:19:47 EDT 1986 

14791 

Sun 

% cl 

Sun Sep 28 12:19:47 EDT 1986 

14792 

Fri 

% cl 

Fri Sep 26 12:19:47 EDT 1986 

14793 

September 

%B 

Mon Sep 1 12:19:47 EDT 1986 

14794 

January 

%B 

Thu Jan 1 12:19:47 EST 1987 

14795 

December 

%B 

Mon Dec 1 12:19:47 EST 1986 

14796 

Sep Mon 

%b %a 

Mon Sep 1 12:19:47 EDT 1986 

14797 

Jan Fri 

%b %a 

Fri Jan 2 12:19:47 EST 1987 

14798 

Dec Mon 

%b %a 

Mon Dec 1 12:19:47 EST 1986 

14799 

Jan Wed 1989 

%b %a %Y 

Wed Jan 4 12:19:47 EST 1989 

14800 

Fri 9 

%a %H 

Fri Sep 26 09:00:00 EDT 1986 

14801 

Feb 10:30 

%b %H:%S 

Sun Feb 1 10:00:30 EST 1987 

14802 

10:30 

%H: %M 

Tue Sep 23 10:30:00 EDT 1986 

14803 

13:30 

%H: %M 

Mon Sep 22 13:30:00 EDT 1986 


14804 APPLICATION USAGE 

14805 Although historical versions of getdate () did not require that <time.h> declare the external 

14806 variable getdate_err, this volume of IEEE Std. 1003.1-200x does require it. The Open Group 

14807 encourages applications to remove declarations of getdate_err and instead incorporate the 

14808 declaration by including <time.h>. 

14809 Applications should use %Y (4-digit years) in preference to %y (2-digit years). 

14810 RATIONALE 

14811 None. 

14812 FUTURE DIRECTIONS 

14813 None. 

14814 SEE ALSO 

14815 ctime(), localtime (), setlocale(), strftime(), times (), the System Interface Definitions volume of 

14816 IEEE Std. 1003.1-200x, <time.h> 

14817 CHANGE HISTORY 

14818 First released in Issue 4, Version 2. 

14819 Issue 5 

14820 Moved from X/OPEN UNIX extension to BASE. 

14821 The last paragraph of the DESCRIPTION is added. 

14822 The %C specifier is added, and the exact meaning of the %y specifier is clarified in the 

14823 DESCRIPTION. 

14824 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 
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14825 

14826 

14827 

14828 

14829 


The %R specifier is changed to follow historical practice. I 

Issue 6 I 

The DESCRIPTION is updated to refer to "seconds since the Epoch" rather than "seconds since I 
00:00:00 UTC (Coordinated Universal Time), January 1 1980" for consistency with other time I 
functions. I 
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14830 

14831 

14832 

14833 

14834 

14835 

14836 

14837 

14838 

14839 

14840 

14841 

14842 

14843 

14844 

14845 

14846 

14847 

14848 

14849 

14850 

14851 

14852 

14853 

14854 

14855 

14856 

14857 

14858 

14859 

14860 

14861 

14862 

14863 

14864 

14865 

14866 

14867 


NAME 

getegid — get the effective group ID 

SYNOPSIS 

#include <unistd.h> 
gid_t getegid(void) ; 

DESCRIPTION 

The getegid() function shall return the effective group ID of the calling process. 

RETURN VALUE 

The getegid () function is always successful and no return value is reserved to indicate an error. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

getgidO , setgid (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

<sys/types.h>, <unistd.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 
XSI-conformant systems. 

The <unistd.h> header is added to the SYNOPSIS section. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The argument list is explicitly defined as void. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 
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14868 NAME 

14869 getenv — get value of an environment variable 

14870 SYNOPSIS 

14871 #include <stdlib.h> 

14872 char *getenv (const char * name) ; 

14873 DESCRIPTION 

14874 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

14875 conflict between the requirements described here and the ISO C standard is unintentional. This I 

14876 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

14877 The getenv () function shall search the environment of the calling process (see the System I 

14878 Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables) for the I 

14879 environment variable name if it exists and return a pointer to the value of the environment I 

14880 variable. If the specified environment variable cannot be found, a null pointer shall be returned. I 

14881 The application shall ensure that it does not modify the string pointed to by the getenv () I 

14882 function. The string pointed to may be overwritten by a subsequent call to getenv(), setenv(), I 

14883 xsi unsetenv{ ), or pntenv( )but shall not be overwritten by a call to any other function in this volume I 

14884 of IEEE Std. 1003.1-200x. 

14885 If the application modifies environ or the pointers to which it points, the behavior of getenv () is I 

14886 undefined. I 

14887 cx The getenv () function need not be reentrant. A function that is not required to be reentrant is not I 

14888 required to be thread-safe. 

14889 RETURN VALUE 

14890 Upon successful completion, getenv() shall return a pointer to a string containing the value for 

14891 the specified name. If the specified name cannot be found in the environment of the calling I 

14892 process, a null pointer shall be returned. I 

14893 The return value from getenv () may point to static data which may be overwritten by 

14894 xsi subsequent calls to getenv( ), setenv( ), unsetenv{ ), or putenv( ). I 

14895 ERRORS 

14896 No errors are defined. 

14897 EXAMPLES 

14898 Getting the Value of an Environment Variable 

14899 The following example gets the value of the HOME environment variable. 

14900 tinclude <stdlib.h> 

14901 

14902 const char *name = "HOME"; 

14903 char *value; 

14904 value = getenv (name); 

14905 APPLICATION USAGE 

14906 None. 

14907 RATIONALE 

14908 Additional functions putenv () and clearenv() were considered but rejected because they were 

14909 considered to be more oriented towards system administration than ordinary application 

14910 programs. This was reconsidered because uses from within an application have been identified 

14911 since the original decision was made. The putenv() function has now been included for 
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14912 alignment with the Single UNIX Specification. I 

14913 The getenv() function is inherently not reentrant because it returns a value pointing to static I 

14914 data. I 

14915 Conforming applications are required not to modify environ directly, but to use only the I 

14916 functions described here to manipulate the process environment as an abstract object. Thus, the I 

14917 implementation of the environment access functions has complete control over the data I 

14918 structure used to represent the environment (subject to the requirement that environ be I 

14919 maintained as a list of strings with embedded equal signs for applications that wish to scan the I 

14920 environment). This constraint allows the implementation to properly manage the memory it I 

14921 allocates, either by using allocated storage for all variables (copying them on the first invocation I 

14922 of setenv( ) or unsetenv( )), or keeping track of which strings are currently in allocated space and I 

14923 which are not, via a separate table or some other means. This enables the implementation to free I 

14924 any allocated space used by strings (and perhaps the pointers to them) stored in environ when I 

14925 unsetenv () is called. A C runtime start-up procedure (that which invokes main{) and perhaps I 

14926 initializes environ ) can also initialize a flag indicating that none of the environment has yet been I 

14927 copied to allocated storage, or that the separate table has not yet been initialized. I 

14928 In fact, for higher performance of getenv(), the implementation could also maintain a separate I 

14929 copy of the environment in a data structure that could be searched much more quickly (such as I 

14930 an indexed hash table, or a binary tree), and update both it and the linear list at environ when I 

14931 setenv( ) or unsetenv( ) is invoked. I 

14932 Performance of getenv() can be important for applications which have large numbers of I 

14933 environment variables. Typically, applications like this use the environment as a resource I 

14934 database of user-configurable parameters. The fact that these variables are in the user's shell I 

14935 environment usually means that any other program that uses environment variables (such as Is, I 

14936 which attempts to use COLUMNS, or really almost any utility (LANG, LC_ALL, and so on) is I 

14937 similarly slowed down by the linear search through the variables. I 

14938 An implementation that maintains separate data structures, or even one that manages the I 

14939 memory it consumes, is not currently required as it was thought it would reduce consensus I 

14940 among implementors who do not want to change their historical implementations. I 

14941 The POSIX Threads Extension states that multi-threaded applications must not modify environ I 

14942 directly, and that IEEE Std. 1003.1-200x is providing functions which such applications can use I 

14943 in the future to manipulate the environment in a thread-safe manner. Thus, moving away from I 

14944 application use of environ is desirable from that standpoint as well. I 

14945 FUTURE DIRECTIONS 

14946 None. 

14947 SEE ALSO 

14948 exec, pntenv(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h>, the I 

14949 System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment Variables I 

14950 CHANGE HISTORY 

14951 First released in Issue 1. 

14952 Derived from Issue 1 of the SVID. 


14953 Issue 4 

14954 

14955 

14956 


The DESCRIPTION is updated to indicate that the return string must not be modified by an 
application, may be overwritten by subsequent calls to getenv() or putenv (), and is not 
overwritten by calls to other XSI system interfaces. 
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14957 

14958 

14959 

14960 

14961 

14962 

14963 

14964 

14965 

14966 

14967 


A reference to putenv () has also been added to the APPLICATION USAGE section. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The type of argument name is changed from char* to const char*. 

Issue 5 

Normative text previously in the APPLICATION USAGE section is moved to the RETURN 
VALUE section. 

A note indicating that this function need not be reentrant is added to the DESCRIPTION. 

Issue 6 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• References added to the new setenv {) and unset env () functions. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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14968 

14969 

14970 

14971 

14972 

14973 

14974 

14975 

14976 

14977 

14978 

14979 

14980 

14981 

14982 

14983 

14984 

14985 

14986 

14987 

14988 

14989 

14990 

14991 

14992 

14993 

14994 

14995 

14996 

14997 

14998 

14999 

15000 

15001 

15002 

15003 

15004 

15005 


NAME 

geteuid — get the effective user ID 

SYNOPSIS 

#include <unistd.h> 
uid_t geteuid(void) ; 

DESCRIPTION 

The getenid() function shall return the effective user ID of the calling process. 

RETURN VALUE 

The geteuid () function is always successful and no return value is reserved to indicate an error. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

getuidi ), setuid (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

<sys/types.h>, <unistd.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 
XSI-conformant systems. 

The <unistd.h> header is added to the SYNOPSIS section. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The argument list is explicitly defined as void. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 
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15007 

15008 

15009 

15010 

15011 

15012 

15013 

15014 

15015 

15016 

15017 

15018 

15019 

15020 

15021 

15022 

15023 

15024 

15025 

15026 

15027 

15028 

15029 

15030 

15031 

15032 

15033 

15034 

15035 

15036 

15037 

15038 

15039 

15040 

15041 

15042 

15043 


NAME 

getgid — get the real group ID 

SYNOPSIS 

#include <unistd.h> 
gid_t getgid(void) ; 

DESCRIPTION 

The getgid () function shall return the real group ID of the calling process. 

RETURN VALUE 

The getgid () function is always successful and no return value is reserved to indicate an error. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

getnid(), setgid (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

<sys/types.h>, <unistd.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 
XSI-conformant systems. 

The <unistd.h> header is added to the SYNOPSIS section. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The argument list is explicitly defined as void. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 
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15044 NAME 

15045 getgrent — get the group database entry 

15046 SYNOPSIS 

15047 xsi tinclude <grp.h> 

15048 struct group *getgrent (void) ; 

15049 

15050 DESCRIPTION 

15051 Refer to endgrent(). 
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15052 NAME 

15053 getgrgid, getgrgid_r — get group database entry for a group ID 

15054 SYNOPSIS 

15055 tinclude <grp.h> 

15056 struct group *getgrgid(gid_t gid) ; 

15057 TSF int getgrgid_r (gid_t gid, struct group *grp, char * buffer, 

15058 size_t bufsize, struct group **result) ; 

15059 

15060 DESCRIPTION 

15061 The getgrgid () function shall search the group database for an entry with a matching gid. 

15062 The getgrgid () function need not be reentrant. A function that is not required to be reentrant is 

15063 not required to be thread-safe. 

15064 tsf The getgrgid_r( ) function updates the group structure pointed to by grp and stores a pointer to 

15065 that structure at the location pointed to by result. The structure contains an entry from the 

15066 group database with a matching gid. Storage referenced by the group structure is allocated from 

15067 the memory provided with the buffer parameter, which is bufsize characters in size. The 

15068 maximum size needed for this buffer can be determined with the {_SC_GETGR_R_SIZE_MAX} 

15069 s ysconf( ) parameter. A NULL pointer is returned at the location pointed to by result on error or if 

15070 the requested entry is not found. 

15071 RETURN VALUE 

15072 Upon successful completion, getgrgid () shall return a pointer to a struct group with the structure 

15073 defined in <grp.h> with a matching entry if one is found. The getgrgid () function shall return a 

15074 man null pointer if either the requested entry was not found, or an error occurred. On error, errno 

15075 shall be set to indicate the error. 

15076 The return value may point to a static area which is overwritten by a subsequent call to 

15077 getgrent( ), getgrgid (), or getgrnam( ). 

15078 tsf If successful, the getgrgid_r() function shall return zero; otherwise, an error number shall be 

15079 returned to indicate the error. 

15080 ERRORS 

15081 man The getgrgid () and getgrgid_r( ) functions may fail if: 

15082 man [EIO] An 1/O error has occurred. 

15083 man [EINTR] A signal was caught during getgrgid (). 

15084 man [EMFILE] |OPEN_MAX} file descriptors are currently open in the calling process. 

15085 man [ENFILE] The maximum allowable number of files is currently open in the system. 

15086 tsf The getgrgid_r( ) function may fail if: 

15087 tsf [ERANGE] Insufficient storage was supplied via buffer and bufsize to contain the data to 

15088 be referenced by the resulting group structure. 
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15089 

15090 

15091 

15092 

15093 

15094 

15095 

15096 

15097 

15098 

15099 

15100 

15101 

15102 

15103 

15104 

15105 

15106 

15107 

15108 

15109 

15110 

15111 

15112 

15113 

15114 

15115 

15116 

15117 

15118 

15119 

15120 

15121 

15122 

15123 

15124 

15125 

15126 

15127 

15128 


EXAMPLES 

Finding an Entry in the Group Database 

The following example uses getgrgid () to search the group database for a group ID that was 
previously stored in a stat structure, then prints out the group name if it is found. If the group is 
not found, the program prints the numeric value of the group for the entry. 

#include <sys/types.h> 

#include <grp.h> 

#include <stdio.h> 

struct stat statbuf; 
struct group *grp; 

if ((grp = getgrgid (statbuf.st_gid)) != NULL) 

printf (" %-8.8s", grp->gr_name); 

else 

printf (" %-8d", statbuf.st_gid); 


APPLICATION USAGE 

Applications wishing to check for error situations should set errno to 0 before calling getgrgid (). 
If errno is set on return, an error occurred. 

The getgrgid_r () function is thread-safe and shall return values in a user-supplied buffer instead 
of possibly using a static data area that may be overwritten by each call. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

endgrent(), getgrnam(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

<grp.h>, <limits.h>, <sys/types.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from System V Release 2.0. 

Issue 4 

The DESCRIPTION is clarified. 

In the RETURN VALUE section, the reference to the setting of errno is marked as an extension. 

The errors [EIO], [EINTR], [EMFILE], and [ENFILE] are marked as extensions. 

A note is added to the APPLICATION USAGE section advising how applications should check 
for errors. 

The <sys/types.h> header is added as optional (OH); this header need not be included on XSI- 
conformant systems. 
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15130 

15131 

15132 

15133 

15134 

15135 

15136 

15137 

15138 

15139 

15140 

15141 

15142 

15143 

15144 

15145 

15146 

15147 

15148 

15149 

15150 


Issue 5 

Normative text previously in the APPLICATION USAGE section is moved to the RETURN 
VALUE section. 

The getgrgid_r () function is included for alignment with the POSIX Threads Extension. 

A note indicating that the getgrgid() function need not be reentrant is added to the 
DESCRIPTION. 


Issue 6 

The getgrgid_r{) function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS 
option. 

The Open Group corrigenda item U028/3 has been applied correcting text in the DESCRIPTION 
describing matching the gid. 

In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• In the RETURN VALUE section, the requirement to set errno on error is added. 

• The [EIO], [EINTR], [EMFILE], and [ENFILE] optional error conditions are added. 

The APPLICATION USAGE section is updated to include a note on the thread-safe function and 
its avoidance of possibly using a static data area. 


System Interfaces, Issue 6 


471 



getgrnam() 


System Interfaces 


15151 

15152 

15153 

15154 

15155 

15156 

15157 

15158 

15159 

15160 

15161 

15162 

15163 

15164 

15165 

15166 

15167 

15168 

15169 

15170 

15171 

15172 

15173 

15174 

15175 

15176 

15177 

15178 

15179 

15180 

15181 

15182 

15183 

15184 

15185 

15186 

15187 


NAME 

getgmam, getgmam_r — search group database for a name 

SYNOPSIS 

#include <grp.h> 

struct group *getgrnam(const char * name ); 

TSF int getgrnam_r(const char *name, struct group *grp, char * buffer, 

size_t bufsize, struct group **result ); 


DESCRIPTION 

The getgmam () function shall search the group database for an entry with a matching name. 

The getgmam () function need not be reentrant. A function that is not required to be reentrant is 
not required to be thread-safe. 

tsf The getgrnam_r( ) function updates the group structure pointed to by grp and stores a pointer to 
that structure at the location pointed to by result. The structure contains an entry from the 
group database with a matching gid or name. Storage referenced by the group structure is 
allocated from the memory provided with the buffer parameter, which is bufsize characters in 
size. The maximum size needed for this buffer can be determined with the 
{_SC_GETGR_R_SIZE_MAX} sysconf() parameter. A NULL pointer is returned at the location 
pointed to by residt on error or if the requested entry is not found. 

RETURN VALUE 

The getgrnam() function shall return a pointer to a struct group with the structure defined in 
<grp.h> with a matching entry if one is found. The getgrnam() function shall return a null 
man pointer if either the requested entry was not found, or an error occurred. On error, errno shall be 
set to indicate the error. 

The return value may point to a static area which is overwritten by a subsequent call to 
getgrent (), getgrgid (), or getgrnam (). 

tsf If successful, the getgrnam_r( ) function shall return zero; otherwise, an error number shall be 
returned to indicate the error. 

ERRORS 

man The getgrnam( ) and getgrnam_r( ) functions may fail if: 

man [EIO] An 1/O error has occurred. 

man [EINTR] A signal was caught during getgrnam (). 

man |OPEN_MAX} file descriptors are currently open in the calling process. 

man [ENFILE] The maximum allowable number of files is currently open in the system. 

The getgrnam_r( ) function may fail if: 

tsf [ERANGE] Insufficient storage was supplied via buffer and bufsize to contain the data to 

be referenced by the resulting group structure. 
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15189 

15190 

15191 

15192 

15193 

15194 

15195 

15196 

15197 

15198 

15199 

15200 

15201 

15202 

15203 

15204 

15205 

15206 

15207 

15208 

15209 

15210 

15211 

15212 

15213 

15214 

15215 

15216 

15217 

15218 

15219 

15220 

15221 

15222 

15223 

15224 

15225 

15226 

15227 


EXAMPLES 

None. 

APPLICATION USAGE 

Applications wishing to check for error situations should set errno to 0 before calling getgrnam (). 
If errno is set on return, an error occurred. 

The getgrnam_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 
of possibly using a static data area that may be overwritten by each call. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

endgrent( ), getgrgid(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <grp.h>, 
<limits.h>, <sys/types.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from System V Release 2.0. 

Issue 4 

The DESCRIPTION is clarified. 

The <sys/types.h> header is added as optional (OH); this header need not be included on XSI- 
conformant systems. 

In the RETURN VALUE section, reference to the setting of errno is marked as an extension. 

The errors [EIO], [EINTR], [EMFILE], and [ENFILE] are marked as extensions. 

A note is added to the APPLICATION USAGE section advising how applications should check 
for errors. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The type of argument name is changed from char* to const char*. 

Issue 5 

Normative text previously in the APPLICATION USAGE section is moved to the RETURN 
VALUE section. 

The getgrnam_r( ) function is included for alignment with the POSIX Threads Extension. 

A note indicating that the getgrnam() function need not be reentrant is added to the 
DESCRIPTION. 

Issue 6 

The getgrnam_r() function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS 
option. 

In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 
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15228 

15229 

15230 

15231 

15232 

15233 

15234 


• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• In the RETURN VALUE section, the requirement to set errno on error is added. 

• The [EIO], [EINTR], [EMFILE], and [ENFILE] optional error conditions are added. 

The APPLICATION USAGE section is updated to include a note on the thread-safe function and 
its avoidance of possibly using a static data area. 
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15235 NAME 

15236 getgroups — get supplementary group IDs I 

15237 SYNOPSIS 

15238 tinclude <unistd.h> 

15239 int getgroups (int gidsetsize, gid_t grouplist [] ) ; 

15240 DESCRIPTION 

15241 The getgroups () function fills in the array grouplist with the current supplementary group IDs of I 

15242 the calling process. It is implementation-dependent whether getgroups () also returns the I 

15243 effective group ID in the grouplist array. I 

15244 The gidsetsize argument specifies the number of elements in the array grouplist. The actual I 

15245 number of group IDs stored in the array is returned. The values of array entries with indices I 

15246 greater than or equal to the value returned are undefined. I 

15247 If gidsetsize is 0, getgroups () shall return the number of group IDs that it would otherwise return I 

15248 without modifying the array pointed to by grouplist . I 

15249 If the effective group ID of the process is returned with the supplementary group IDs, the value I 

15250 returned shall always be greater than or equal to one and less than or equal to the value of I 

15251 |NGROUPS_MAX}+l. If the effective group ID of the process is not returned with the I 

15252 supplementary group IDs and |NGROUPS_MAX} is zero, the function shall return zero. I 

15253 RETURN VALUE 

15254 Upon successful completion, the number of supplementary group IDs shall be returned. A 

15255 return value of -1 indicates failure and errno shall be set to indicate the error. 

15256 ERRORS 

15257 The getgroups () function shall fail if: 

15258 [EINVAL] The gidsetsize argument is non-zero and is less than or equal to the number of I 

15259 supplementary group IDs. I 

15260 EXAMPLES 

15261 Getting the Supplementary Group IDs of the Calling Process 

15262 The following example places the current supplementary group IDs of the calling process into 

15263 the group array. 

15264 #include <sys/types .h> 

15265 tinclude <unistd.h> 

15266 #include <limits.h> 

15267 

15268 gid_t group [_POSIX_NGROUPS_MAX] ; 

15269 int nogroups; 

15270 nogroups = getgroups (_POSIX_NGROUPS_MAX, group) ; 

15271 APPLICATION USAGE 

15272 None. 

15273 RATIONALE 

15274 The related function setgroups() is a privileged operation and therefore is not covered by this 

15275 volume of IEEE Std. 1003.1-200x. 

15276 As implied by the definition of supplementary groups, the effective group ID may appear in the 

15277 array returned by getgroups () or it may be returned only by getegid (). Duplication may exist, but 
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15278 the application needs to call getegid() to be sure of getting all of the information. Various 

15279 implementation variations and administrative sequences cause the set of groups appearing in 

15280 the result of getgroups () to vary in order and as to whether the effective group ID is included, 

15281 even when the set of groups is the same (in the mathematical sense of "set”). (The history of a 

15282 process and its parents could affect the details of result.) 

15283 Applications writers should note that |NGROUPS_MAX} is not necessarily a constant on all 

15284 implementations. 

15285 FUTURE DIRECTIONS 

15286 None. 

15287 SEE ALSO 

15288 getegid(), setgid (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

15289 <sys/types.h>, <unistd.h> 

15290 CHANGE HISTORY 

15291 First released in Issue 3. 

15292 Entry included for alignment with the POSIX.1-1988 standard. 

15293 Issue 4 

15294 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

15295 XSI-conformant systems. 

15296 The <unistd.h> header is added to the SYNOPSIS section. 

15297 The following change is incorporated for alignment with the FIPS requirements: 

15298 • A return value of 0 is no longer permitted, because |NGROUPS_MAX} cannot be 0. 

15299 Issue 5 

15300 Normative text previously in the APPLICATION USAGE section is moved to the 

15301 DESCRIPTION. 

15302 Issue 6 

15303 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

15304 The following new requirements on POSIX implementations derive from alignment with the 

15305 Single UNIX Specification: 

15306 • The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 

15307 required for conforming implementations of previous POSIX specifications, it was not 

15308 required for UNIX applications. 

15309 • A return value of 0 is not permitted, because |NGROUPS_MAX} cannot be 0. This is a FIPS 

15310 requirement. 

15311 The following changes were made to align with the IEEE P1003.1a draft standard: I 

15312 • Explanation added that the effective group ID may be included in the supplementary group I 

15313 list. I 
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15314 NAME I 

15315 gethostbyaddr (LEGACY), gethostbyname (LEGACY), getipnodebyaddr, getipnodebyname, — I 

15316 network host database functions I 

15317 SYNOPSIS I 

15318 tinclude <netdb.h> | 

15319 struct hostent *gethostbyaddr (const void *ac?dr, socklen_t Jen, I 

15320 int type) ; I 

15321 struct hostent *gethostbyname (const char * name) ; I 

15322 struct hostent *getipnodebyaddr(const void *addr, socklen_t Jen, I 

15323 int type, int * error_num) ; | 

15324 struct hostent *getipnodebyname (const char *name, int type, int flags, I 

15325 int * error_num) ; \ 

15326 DESCRIPTION I 

15327 These functions enable applications to retrieve information about hosts. This information is I 

15328 considered to be stored in a database that can be accessed sequentially or randomly. I 

15329 Implementation of this database is unspecified. I 

15330 Note: In many cases it is implemented by the Domain Name System, as documented in I 

15331 RFC 1034, RFC 1035, and RFC 1886. I 

15332 Entries are returned in hostent structures. I 

15333 The gethostbyaddr () function shall return an entry containing addresses of address family type for I 

15334 the host with address addr. ten contains the length of the address pointed to by addr. The I 

15335 gethostbyaddr () function need not be reentrant. A function that is not required to be reentrant is I 

15336 not required to be thread-safe. I 

15337 The gethostbyname () function shall return an entry containing addresses of address family I 

15338 AF_INET for the host with name name. The gethostbyname () function need not be reentrant. A I 

15339 function that is not required to be reentrant is not required to be thread-safe. I 

15340 The getipnodebyaddr () function shall return the entry containing addresses of address family type I 

15341 for the host with address addr, opening a connection to the database if necessary. The ten I 

15342 argument contains the length of the address pointed to by addr. If an error occurs, the I 

15343 appropriate error code is returned in error_nnm. The getipnodebyaddr () function is thread-safe. I 

15344 The getipnodebyname () function shall return the entry containing addresses of address family I 

15345 type for the host with name name, opening a connection to the database if necessary. The flags I 

15346 argument affects what information is returned. If an error occurs, the appropriate error code is I 

15347 returned in error_num. The getipnodebyname () function is thread-safe. I 

15348 The addr argument of gethostbyaddr () or getipnodebyaddr () shall be an in_addr structure when I 

15349 iP6 type is AF_INET, and shall be an in6_addr structure when type is AF_INET6. It contains a binary I 

15350 format (that is, not null-terminated) address in network byte order. The gethostbyaddr () function I 

15351 is not guaranteed to return addresses of address families other than AF_INET, even when such I 

15352 addresses exist in the database. I 

15353 If gethostbyaddr () or getipnodebyaddr () returns a record, then its h_addrtype field is the same as the I 

15354 type argument that was passed to the function, and its h_addr_list field lists a single address that I 

15355 iP6 is a copy of the addr argument that was passed to the function. If type is AF_INET6 and addr is I 

15356 an IPv4-mapped IPv6 address or an IPv4-compatible IPv6 address, then the h_name and h_aliases I 

15357 fields are those that would have been returned for address family AF_INET and address equal to I 

15358 the last four bytes of addr. I 
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15359 If gethostbyaddr() or getipnodebyaddr() are called with addr containing the IPv6 unspecified 

15360 address (all bytes zero), then no query is performed and the function fails with 

15361 [HOST_NOT_FOUND]. 

15362 The name argument of getipnodebyname() shall be either a node name or a numeric address 

15363 string. For IPv4, a numeric address string shall be in the dotted-decimal notation described in 

15364 iP6 inet_addr(). For IPv6, a numeric address string shall be in one of the standard IPv6 text forms 

15365 described in <REFERENCE UNDEFINED>(inet_pton). The name argument of gethostbyname() 

15366 shall be a node name; the behavior of get host byname ( ) when passed a numeric address string is 

15367 unspecified. 

15368 iP6 If name is a dotted-decimal IPv4 address and af equals AF_INET, or name is an IPv6 hex address 

15369 and af equals AF_INET6,the members of the returned hostent structure are as follows: 

15370 h_name Points to a copy of the name argument. 

15371 h_aliases A NULL pointer. 

15372 h_addrtype A copy of the type argument. 

15373 iP6 hjength Either 4 (for AF_INET) or 16 (for AF_INET6). 

15374 iP6 h_addr_list[ 0] A pointer to the 4-byte or 16-byte binary address. 

15375 h_addr_list[ 1] A NULL pointer. 

15376 IP6 If name is a dotted-decimal IPv4 address and af equals AF_INET6 and AI_V4MAPPED is set in 

15377 fl a S s , an IPv4-mapped IPv6 address is returned, and the members are as follows: 

15378 h_name Points to an IPv6 hex address containing the IPv4-mapped IPv6 address. 

15379 h_aliases A NULL pointer. 

15380 h_addrtype AF_INET6. 

15381 hjength 16. 

15382 h_addrjist[ 0] A pointer to the 16-byte binary address. 

15383 h_addrjist[ 1] A NULL pointer. 

15384 If name is a dotted-decimal IPv4 address and af equals AF_INET6 and AI_V4MAPPED is not set, 

15385 then NULL is returned with [HOST_NOT_FOUND], 

15386 It is an error when name is an IPv6 hex address and af equals AF_INET. The function's return 

15387 value is a NULL pointer with the [HOST_NOT_FOUND] error. 

15388 If name is not a numeric address string and is an alias for a valid host name, then gethostbyname( ) 

15389 or getipnodebyname( ) return information about the host name to which the alias refers, and name 

15390 is included in the list of aliases returned. 

15391 If name is a node name, then operation of the getipnodebyname () function is modified by the value 

15392 of the flags argument, as follows: 

15393 • If flags is 0 and type is AF_INET, then a query is made for IPv4 addresses. If it is successful, 

15394 the IPv4 addresses are returned and the hjength member of the hostent structure shall have 

15395 iP6 a value of 4. Otherwise, the function shall return a NULL pointer. 

15396 • If flags is 0 and if type is AF_INET6, then a query is made for IPv6 addresses. If it is successful, 

15397 the IPv6 addresses are returned and the hjength member of the hostent structure shall have 

15398 a value of 16. If unsuccessful, the function shall return a NULL pointer. 
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• If the AI_V4MAPPED flag is set and type is AF_INET6, then a query is made for IPv6 
addresses. If it is successful, the IPv6 addresses are returned, and no query is made for IPv4 
addresses. If it is not successful, a query is made for IPv4 addresses and any found are 
returned as IPv4-mapped IPv6 addresses. h_length shall have a value of 16 in either case of 
addresses being returned. The AI_V4MAPPED flag is ignored unless type is AF_INET6. 

• If the AI_ALL and AI_V4MAPPED flags are both set and type is AF_INET6, then a query is 
made for IPv6 addresses, and any found are returned. Another query is then made for IPv4 
addresses, and any found are returned as IPv4-mapped IPv6 addresses, and hjength is 16. 
Only if both queries fail does the function return a NULL pointer. This flag is ignored unless 
type is AF_INET6. 

• The AI_ADDRCONFIG flag specifies that a query for IPv6 addresses should be made only if 
the node has at least one IPv6 source address configured, and that a query for IPv4 addresses 
should be made only if the node has at least one IPv4 source address configured. 

• If the AI_V4MAPPED and AI_ADDRCONFIG flags are both set and type is AF_INET6, then: 

— If the node has at least one IPv6 source address configured, a query is made for IPv6 
addresses. 

— If it is successful, the IPv6 addresses are returned and no query is made for IPv4 
addresses. 

— If the node has no IPv6 source address configured, or if the query for IPv6 addresses is not 
successful, then if the node has at least one IPv4 source address configured, a query is 
made for IPv4 addresses and any found are returned as IPv4-mapped IPv6 addresses. 

hjength shall have a value of 16 in either case of addresses being returned. 

. Macro AI_DEFAULT is defined as the logical OR of AI_V4MAPPED and AI_ADDRCONFIG. 

Note: It is intended that setting flags to AI_DEFAULT be appropriate for most 

applications. 

RETURN VALUE 

Upon successful completion, these functions shall return a pointer to a ho stent structure if the 
requested entry was found, and a null pointer if the end of the database was reached or the 
requested entry was not found. 

Upon unsuccessful completion, getipnodebyaddr( ) and getipnodebyname () shall set their error_nnm 
argument to indicate the error, while gethostbyaddr() and get host byname ( ) shall set h_errno to 
indicate it. 

ERRORS 

These functions shall fail in the following cases. The getipnodebyaddr( ) and getipnodebyname () 
functions shall return the value shown in the list below in error_num ; the gethostbyaddr() and 
gethostbyname( ) functions shall set h_errno to that value. Any changes to errno are unspecified. 

[HOST_NOT_FOUND] 

No such host is known. 

[NO_DATA] The server recognized the request and the name, but no address is available. 

Another type of request to the name server for the domain might return an 
answer. 

[NO_RECOVERY] 

An unexpected server failure occurred which cannot be recovered. 
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15442 [TRY_AGAIN] A temporary and possibly transient error occurred, such as a failure of a 

15443 server to respond. 

15444 EXAMPLES 

15445 None. 

15446 APPLICATION USAGE 

15447 The hostent structure returned by getipnodebyaddr( ) and getipnodebyname (), and any structures 

15448 pointed to from those structures, are dynamically allocated. Applications should call 

15449 freehostent ( ) to free the memory used by these structures. 

15450 The gethostbyaddr( ), and gethostbyname( ) functions may return pointers to static data, which may 

15451 be overwritten by subsequent calls to any of these functions. Applications shall not call 

15452 freehostent() for this area. 

15453 The getipnodebyaddr( ) function is preferred over the gethostbyaddr( ) function. 

15454 The getipnodebyname () function is preferred over the gethostbyname( ) function. 

15455 RATIONALE 

15456 None. 

15457 FUTURE DIRECTIONS 

15458 The gethostbyaddr( ) and get host byname ( ) functions may be withdrawn in a future version. 

15459 SEE ALSO 

15460 endhostent( ), freehostent(), endservent(), inet_addr(), the System Interface Definitions volume of 

15461 IEEE Std. 1003.1-200x, <netdb.h> 

15462 CHANGE HISTORY 

15463 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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15464 NAME 

15465 gethostbyname — network host database functions 

15466 SYNOPSIS 

15467 #include <netdb.h> 

15468 struct hostent *gethostbyname (const char 

15469 DESCRIPTION 

15470 Refer to gethostbyaddr (). 


* name) ; 
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15471 NAME 

15472 gethostent — network host database functions 

15473 SYNOPSIS 

15474 #include <netdb.h> 

15475 struct hostent *gethostent (void) ; 

15476 DESCRIPTION 

15477 Refer to endhostent (). 
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15478 NAME 

15479 gethostid — get an identifier for the current host 

15480 SYNOPSIS 

15481 xsi tinclude <unistd.h> 

15482 long gethostid (void) ; 

15483 

15484 DESCRIPTION 

15485 The gethostid () function retrieves a 32-bit identifier for the current host. 

15486 RETURN VALUE 

15487 Upon successful completion, gethostid () shall return an identifier for the current host. 

15488 ERRORS 

15489 No errors are defined. 

15490 EXAMPLES 

15491 None. 

15492 APPLICATION USAGE 

15493 This volume of IEEE Std. 1003.1-200x does not define the domain in which the return value is 

15494 unique. 

15495 RATIONALE 

15496 None. 

15497 FUTURE DIRECTIONS 

15498 None. 

15499 SEE ALSO 

15500 random (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

15501 CHANGE HISTORY 

15502 First released in Issue 4, Version 2. 

15503 Issue 5 

15504 Moved from X/OPEN UNIX extension to BASE. 
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15505 NAME 

15506 gethostname — get name of current host 

15507 SYNOPSIS 

15508 tinclude <unistd.h> 

15509 int gethostname (char *name, socklen_t namelen) ; 

15510 DESCRIPTION 

15511 The gethostname() function shall return the standard host name for the current machine. The 

15512 namelen argument shall specify the size of the array pointed to by the name argument. The 

15513 returned name shall be null-terminated, except that if namelen is an insufficient length to hold 

15514 the host name, then the returned name shall be truncated and it is unspecified whether the 

15515 returned name is null-terminated. 

15516 Host names are limited to 255 bytes. 

15517 RETURN VALUE 

15518 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned. 

15519 ERRORS 

15520 No errors are defined. 

15521 EXAMPLES 

15522 None. 

15523 APPLICATION USAGE 

15524 None. 

15525 RATIONALE 

15526 None. 

15527 FUTURE DIRECTIONS 

15528 None. 

15529 SEE ALSO 

15530 getliostid(), nname(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

15531 <unistd.h> 

15532 CHANGE HISTORY 

15533 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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15534 NAME 

15535 getipnodebyaddr — network host database functions 

15536 SYNOPSIS 

15537 #include <netdb.h> 

15538 struct hostent *getipnodebyaddr (const void *addr, socklen 

15539 int type, int * error_num) ; 

15540 DESCRIPTION 

15541 Refer to gethostbyaddr (). 


len, 
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15542 NAME 

15543 getipnodebyname — network host database functions 

15544 SYNOPSIS 

15545 tinclude <netdb.h> 

15546 struct hostent *getipnodebyname(const char *name, int type, int flags, 

15547 int * error_num) ; 

15548 DESCRIPTION 

15549 Refer to gethostbyaddr (). 
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15550 NAME 

15551 getitimer, setitimer — get or set value of interval timer 

15552 SYNOPSIS 

15553 xsi tinclude <sys/time.h> 

15554 

15555 

15556 

15557 


int getitimer(int which, struct itimerval *value); 
int setitimer(int which, const struct itimerval *value, 
struct itimerval *ovalue) ; 


15558 DESCRIPTION 

15559 The getitimer( ) function shall store the current value of the timer specified by zvhich into the 

15560 structure pointed to by value. The setitimer () function shall set the timer specified by which to 

15561 the value specified in the structure pointed to by value, and if ovalue is not a null pointer, stores 

15562 the previous value of the timer in the structure pointed to by ovalue. 

15563 A timer value is defined by the itimerval structure, specified in <sys/time.h>. If it_value is non- 

15564 zero, it shall indicate the time to the next timer expiration. If it_interval is non-zero, it shall 

15565 specify a value to be used in reloading it_value when the timer expires. Setting it_value to 0 shall 

15566 disable a timer, regardless of the value of it_interval. Setting it_interval to 0 shall disable a timer 

15567 after its next expiration (assuming it_value is non-zero). 

15568 Implementations may place limitations on the granularity of timer values. For each interval 

15569 timer, if the requested timer value requires a finer granularity than the implementation supports, 

15570 the actual timer value shall be rounded up to the next supported value. 

15571 An XSI-conforming implementation provides each process with at least three interval timers, 

15572 which are indicated by the zvhich argument: 


15573 ITIMER_REAL Decrements in real time. A SIGALRM signal is delivered when this timer 

15574 expires. 


15575 ITIMER_VIRTUAL Decrements in process virtual time. It runs only when the process is 

15576 executing. A SIGVTALRM signal is delivered when it expires. 


15577 

15578 

15579 

15580 


ITIMER_PROF Decrements both in process virtual time and when the system is running 

on behalf of the process. It is designed to be used by interpreters in 
statistically profiling the execution of interpreted programs. Each time the 
ITIMER_PROF timer expires, the SIGPROF signal is delivered. 


15581 The interaction between setitimer () and any of alarm (), sleep (), or usleep( ) is unspecified. 


15582 RETURN VALUE 

15583 Upon successful completion, getitimer () or setitimer () shall return 0; otherwise, -1 shall be 

15584 returned and errno set to indicate the error. 


15585 ERRORS 

15586 The setitimer () function shall fail if: 

15587 [EINVAL] The value argument is not in canonical form. (In canonical form, the number of 

15588 microseconds is a non-negative integer less than 1,000,000 and the number of 

15589 seconds is a non-negative integer.) 

15590 The getitimer( ) and setitimer () functions may fail if: 

15591 [EINVAL] The zvhich argument is not recognized. 
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15592 EXAMPLES 

15593 None. 

15594 APPLICATION USAGE 

15595 None. 

15596 RATIONALE 

15597 None. 

15598 FUTURE DIRECTIONS 

15599 None. 

15600 SEE ALSO 

15601 alarm(), sleep(), timer_getoverrun (), ualarm(), usleepi), the System Interface Definitions volume of 

15602 IEEE Std. 1003.1-200x, <signal.h>, <sys/time.h> 

15603 CHANGE HISTORY 

15604 First released in Issue 4, Version 2. 

15605 Issue 5 

15606 Moved from X/OPEN UNIX extension to BASE. 
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NAME 

getlogin, getlogin_r — get login name 

SYNOPSIS 

#include <unistd.h> 
char *getlogin(void) ; 

TSF int getlogin_r(char *name, size_t namesize ); 

DESCRIPTION 

The getlogin () function shall return a pointer to a string giving a user name associated with the 
calling process, which is the login name associated with the calling process. If getlogin () returns 
a non-null pointer, then that pointer points to the name that the user logged in under, even if 
there are several login names with the same user ID. 

The getlogin () function need not be reentrant. A function that is not required to be reentrant is 
not required to be thread-safe. 

tsf The getlogin_r( ) function puts the name associated by the login activity with the control terminal 
of the current process in the character array pointed to by name. The array is namesize characters 
long and should have space for the name and the terminating null character. The maximum size 
of the login name is {LOGIN_NAME_MAX}. 

If getlogin_r() is successful, name points to the name the user used at login, even if there are 
several login names with the same user ID. 

RETURN VALUE 

Upon successful completion, getlogin () shall return a pointer to the login name or a null pointer 
man if the user's login name cannot be found. Otherwise, it shall return a null pointer and set errno to 
indicate the error. 

The return value from getlogin () may point to static data whose content is overwritten by each 
call. 

tsf If successful, the getlogin_r() function shall return zero; otherwise, an error number shall be 
returned to indicate the error. 

ERRORS 

man The getlogin () and getlogin_r () functions may fail if: 

man [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 

man [ENFILE] The maximum allowable number of files is currently open in the system. 

man [ENXIO] The calling process has no controlling terminal. 

The getlogin_r( ) function may fail if: 

tsf [ERANGE] The value of namesize is smaller than the length of the string to be returned 

including the terminating null character. 
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15643 EXAMPLES 

15644 Getting the User Login Name 

15645 The following example calls the getlogin () function to obtain the name of the user associated 

15646 with the calling process, and passes this information to the getpiunam() function to get the 

15647 associated user database information. 

15648 tinclude <unistd.h> 

15649 #include <sys/types . h> 

15650 tinclude <pwd.h> 

15651 #include <stdio.h> 

15652 

15653 char *lgn; 

15654 struct passwd *pw; 

15655 

15656 if ( (lgn = getlogin () ) == NULL | | (pw = getpwnam (lgn) ) == NULL) { 

15657 fprintf (stderr, "Get of user information failed.\n"); exit (1); 

15658 } 

15659 APPLICATION USAGE 

15660 Three names associated with the current process can be determined: getpivnid(geteuid()) shall 

15661 return the name associated with the effective user ID of the process; getlogin () shall return the 

15662 name associated with the current login activity; and getpiv:rid(getuid()) shall return the name 

15663 associated with the real user ID of the process. 

15664 The getlogin_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 

15665 of possibly using a static data area that may be overwritten by each call. 

15666 RATIONALE 

15667 The getlogin () function returns a pointer to the user's login name. The same user ID may be 

15668 shared by several login names. If it is desired to get the user database entry that is used during 

15669 login, the result of getlogin () should be used to provide the argument to the getpzvnam() 

15670 function. (This might be used to determine the useds login shell, particularly where a single user 

15671 has multiple login shells with distinct login names, but the same user ID.) 

15672 The information provided by the cuserid() function, which was originally defined in the 

15673 POSIX.1-1988 standard and subsequently removed, can be obtained by the following: 

15674 getpwuid (geteuid () ) 

15675 while the information provided by historical implementations of cnserid( ) can be obtained by: 

15676 getpwuid (getuid () ) 

15677 The thread-safe version of this function places the user name in a user-supplied buffer and 

15678 returns a non-zero value if it fails. The non-thread-safe version may return the name in a static 

15679 data area that may be overwritten by each call. 

15680 EUTURE DIRECTIONS 

15681 None. 

15682 SEE ALSO 

15683 getpwnam (), getpivirid(), getenid{), getnid{), the System Interface Definitions volume of 

15684 IEEE Std. 1003.1-200x, <limits.h>, <unistd.h> 
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CHANGE HISTORY 

First released in Issue 1. 

Derived from System V Release 2.0. 

Issue 4 

The <unistd.h> header is added to the SYNOPSIS section. 

In the RETURN VALUE section, reference to the setting of errno is marked as an extension. 

The behavior of the function when the login name cannot be found is included in the RETURN 
VALUE section instead of the DESCRIPTION. 

The errors [EMFILE], [ENFILE], and [ENXIO] are marked as extensions. 

The APPLICATION USAGE section is changed to refer to getpivnid() rather than cnserid (), which 
may be withdrawn in a future version. 

The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

• The argument list is explicitly defined as void. 

• The DESCRIPTION is updated to state explicitly that the return value is a pointer to a string 
giving the user name, rather than simply a pointer to the user name as stated in previous 
issues. 

Issue 5 

Normative text previously in the APPLICATION USAGE section is moved to the RETURN 
VALUE section. 

The getlogin_r () function is included for alignment with the POSIX Threads Extension. 

A note indicating that the get!ogin() function need not be reentrant is added to the 
DESCRIPTION. 

Issue 6 

The getlogin_r() function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS 
option. 

In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the RETURN VALUE section, the requirement to set errno on error is added. 

• The [EMFILE], [ENFILE], and [ENXIO] optional error conditions are added. 

The APPLICATION USAGE section is updated to include a note on the thread-safe function and 
its avoidance of possibly using a static data area. 
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15717 NAME 

15718 getmsg, getpmsg — receive next message from a STREAMS file (STREAMS) 

15719 SYNOPSIS 

15720 XSR tinclude <stropts.h> 

15721 

15722 

15723 

15724 

15725 

15726 DESCRIPTION 

15727 The getmsg () function shall retrieve the contents of a message located at the head of the 

15728 STREAM head read queue associated with a STREAMS file and place the contents into one or 

15729 more buffers. The message contains either a data part, a control part, or both. The data and 

15730 control parts of the message are placed into separate buffers, as described below. The semantics 

15731 of each part are defined by the originator of the message. 

15732 The getpmsg( ) function does the same thing as getmsg) ), but provides finer control over the 

15733 priority of the messages received. Except where noted, all requirements on getmsg) ) also pertain 

15734 to getpmsg (). 

15735 Th e fildes argument specifies a file descriptor referencing a STREAMS-based file. 

15736 The ctlptr and dataptr arguments each point to a strbuf structure, in which the buf member points 

15737 to a buffer in which the data or control information is to be placed, and the maxlen member 

15738 indicates the maximum number of bytes this buffer can hold. On return, the ten member 

15739 contains the number of bytes of data or control information actually received. The ten member is 

15740 set to 0 if there is a zero-length control or data part and ten is set to -1 if no data or control 

15741 information is present in the message. 

15742 When getmsg) ) is called, flagsp should point to an integer that indicates the type of message the 

15743 process is able to receive. This is described further below. 

15744 The ctlptr argument is used to hold the control part of the message, and dataptr is used to hold 

15745 the data part of the message. If ctlptr (or dataptr) is a null pointer or the maxlen member is —1, the 

15746 control (or data) part of the message is not processed and is left on the STREAM head read 

15747 queue, and if the ctlptr (or dataptr) is not a null pointer, len is set to -1. If the maxlen member is 

15748 set to 0 and there is a zero-length control (or data) part, that zero-length part is removed from 

15749 the read queue and len is set to 0. If the maxlen member is set to 0 and there are more than 0 bytes 

15750 of control (or data) information, that information is left on the read queue and len is set to 0. If 

15751 the maxlen member in ctlptr (or dataptr) is less than the control (or data) part of the message, 

15752 maxlen bytes are retrieved. In this case, the remainder of the message is left on the STREAM head 

15753 read queue and a non-zero return value is provided. 

15754 By default, getmsg() processes the first available message on the STREAM head read queue. 

15755 However, a process may choose to retrieve only high-priority messages by setting the integer 

15756 pointed to by flagsp to RS_HIPRI. In this case, getmsg)) shall only process the next message if it is 

15757 a high-priority message. When the integer pointed to by flagsp is 0, any message shall be 

15758 retrieved. In this case, on return, the integer pointed to by flagsp is set to RS_HIPRI if a high- 

15759 priority message was retrieved, or 0 otherwise. 

15760 For getpmsg (), the flags are different. The flagsp argument points to a bitmask with the following 

15761 mutually-exclusive flags defined: MSG_HIPRI, MSG_BAND, and MSG_ANY. Like getmsg) ), 

15762 getpmsg () processes the first available message on the STREAM head read queue. A process may 

15763 choose to retrieve only high-priority messages by setting the integer pointed to by flagsp to 


int getmsg(int fildes, struct strbuf * ctlptr, struct strbuf * dataptr, 
int *flagsp ); 

int getpmsg(int fildes, struct strbuf * ctlptr, struct strbuf *dataptr, 
int *bandp, int * flagsp) ; 
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MSG_HIPRI and the integer pointed to by bandp to 0. In this case, getpmsgi ) shall only process 
the next message if it is a high-priority message. In a similar manner, a process may choose to 
retrieve a message from a particular priority band by setting the integer pointed to by flagsp to 
MSG_BAND and the integer pointed to by bandp to the priority band of interest. In this case, 
getpmsgi ) shall only process the next message if it is in a priority band equal to, or greater than, 
the integer pointed to by bandp, or if it is a high-priority message. If a process just wants to get 
the first message off the queue, the integer pointed to by flagsp should be set to MSG_ANY and 
the integer pointed to by bandp should be set to 0. On return, if the message retrieved was a 
high-priority message, the integer pointed to by flagsp is set to MSG_HIPRI and the integer 
pointed to by bandp shall be set to 0. Otherwise, the integer pointed to by flagsp shall be set to 
MSG_BAND and the integer pointed to by bandp shall be set to the priority band of the message. 

If 0_NONBLOCK is not set, getmsg( ) and getpmsgi ) shall block until a message of the type 
specified by flagsp is available at the front of the STREAM head read queue. If 0_NONBLOCK is 
set and a message of the specified type is not present at the front of the read queue, getmsgi ) and 
getpmsgi ) shall fail and set errno to [EAGAIN]. 

If a hangup occurs on the STREAM from which messages are retrieved, getmsgi ) and getpmsgi ) 
continue to operate normally, as described above, until the STREAM head read queue is empty. 
Thereafter, they return 0 in the len members of ctlptr and dataptr. 

RETURN VALUE 

Upon successful completion, getmsgi ) and getpmsgi) shall return a non-negative value. A value 
of 0 indicates that a full message was read successfully. A return value of MORECTL indicates 
that more control information is waiting for retrieval. A return value of MOREDATA indicates 
that more data is waiting for retrieval. A return value of the bitwise-logical OR of MORECTL 
and MOREDATA indicates that both types of information remain. Subsequent getmsgO and 
getpmsgi ) calls shall retrieve the remainder of the message. However, if a message of higher 
priority has come in on the STREAM head read queue, the next call to getmsgi ) or getpmsgi ) 
shall retrieve that higher-priority message before retrieving the remainder of the previous 
message. 

If the high priority control part of the message is consumed, the message shall be placed back on 
the queue as a normal message of band 0. Subsequent getmsgi ) and getpmsgi ) calls shall retrieve 
the remainder of the message. If, however, a priority message arrives or already exists on the 
STREAM head, the subsequent call to getmsgi ) or getpmsgi ) retrieves the higher-priority 
message before retrieving the remainder of the message that was put back. 

Upon failure, getmsgi ) and getpmsgi ) shall return -1 and set errno to indicate the error. 


ERRORS 


The getmsgi ) and getpmsgi ) functions shall fail if: 

[EAGAIN] The 0_NONBLOCK flag is set and no messages are available. 

[EBADF] The fildes argument is not a valid file descriptor open for reading. 

[EBADMSG] The queued message to be read is not valid for getmsgi ) or getpmsgi ) or a 

pending file descriptor is at the STREAM head. 

[EINTR] A signal was caught during getmsgi ) or getpmsgi )• 

[EINVAL] An illegal value was specified by flagsp, or the STREAM or multiplexer 

referenced by fildes is linked (directly or indirectly) downstream from a 
multiplexer. 

[ENOSTR] A STREAM is not associated with fildes . 


System Interfaces, Issue 6 


493 



getmsgO 


System Interfaces 


15809 

15810 

15811 

15812 

15813 

15814 

15815 

15816 

15817 

15818 

15819 

15820 

15821 

15822 

15823 

15824 

15825 

15826 

15827 

15828 

15829 

15830 

15831 

15832 

15833 

15834 

15835 

15836 

15837 

15838 

15839 

15840 

15841 

15842 

15843 

15844 

15845 

15846 

15847 

15848 

15849 


In addition, getmsgO and getpmsg () shall fail if the STREAM head had processed an 
asynchronous error before the call. In this case, the value of errno does not reflect the result of 
getmsg( ) or getpmsg () but reflects the prior error. 

EXAMPLES 

Getting Any Message 

In the following example, the value of fd is assumed to refer to an open STREAMS file. The call 
to getmsgO retrieves any available message on the associated STREAM-head read queue, 
returning control and data information to the buffers pointed to by ctrlbuf and databuf, 
respectively. 

tinclude <stropts.h> 
int fd; 

char ctrlbuf[128]; 
char databuf[512] ; 
struct strbuf Ctrl; 
struct strbuf data; 
int flags = 0; 
int ret; 

ctrl.buf = ctrlbuf; 

Ctrl.maxlen = sizeof (ctrlbuf); 

data.buf = databuf; 

data.maxlen = sizeof (databuf); 

ret = getmsg (fd, &ctrl, &data, Sflags); 


Getting the First Message off the Queue 

In the following example, the call to getpmsg () retrieves the first available message on the 
associated STREAM-head read queue. 

#include <stropts.h> 
int fd; 

char ctrlbuf[ 128] ; 
char databuf [512]; 
struct strbuf Ctrl; 
struct strbuf data; 
int band = 0; 
int flags = MSG_ANY; 
int ret; 

ctrl.buf = ctrlbuf; 

Ctrl. maxlen = sizeof (ctrlbuf); 

data.buf = databuf; 

data.maxlen = sizeof (databuf); 

ret = getpmsg (fd, &ctrl, &data, &band, Sflags); 
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15850 APPLICATION USAGE 

15851 None. 

15852 RATIONALE 

15853 None. 

15854 FUTURE DIRECTIONS 

15855 None. 

15856 SEE ALSO 

15857 po//(), putmsgO, read(), write (), the System Interface Definitions volume of 

15858 IEEE Std. 1003.1-200x, <stropts.h>. Section 2.6 on page 55 

15859 CHANGE HISTORY 

15860 First released in Issue 4, Version 2. 

15861 Issue 5 

15862 Moved from X/OPEN UNIX extension to BASE. 

15863 A paragraph regarding "high-priority control parts of messages" is added to the RETURN 

15864 VALUE section. 

15865 Issue 6 

15866 This function is marked as part of the XSI STREAMS Option Group. 
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15867 NAME 

15868 getnameinfo — get name information 

15869 Notes to Reviewers 

15870 This section with side shading will not appear in the final copy. - Ed. 

15871 The IPv6 developers believe that getnameinfo () should not truncate the result if the user buffer is 

15872 too small, but return an error status. 

15873 SYNOPSIS 

15874 #include <sys/socket.h> 

15875 #include <netdb.h> 

15876 int getnameinfo(const struct sockaddr *sa, socklen_t salen, 

15877 char *node, socklen_t nodelen, char * service, 

15878 socklen_t servicelen, unsigned int flags) ; 

15879 DESCRIPTION 

15880 The getnameinfo () function translates a socket address to a node name and service location, all of 

15881 which are defined as in getaddrinfo (). 

15882 The sa argument points to a socket address structure to be translated. 

15883 If the node argument is non-NULL and the nodelen argument is non-zero, then the node argument 

15884 points to a buffer able to contain up to nodelen characters that receives the node name as a null- 

15885 terminated string. If the node argument is NULL or the nodelen argument is zero, the node name 

15886 shall not be returned. If the node's name cannot be located, the numeric form of the node's 

15887 address is returned instead of its name. 

15888 If the service argument is non-NULL and the servicelen argument is non-zero, then the service 

15889 argument points to a buffer able to contain up to servicelen characters that receives the service 

15890 name as a null-terminated string. If the service argument is NULL or the servicelen argument is 

15891 zero, the service name shall not be returned. If the service's name cannot be located, the numeric 

15892 form of the service address (for example, its port number) is returned instead of its name. 

15893 The node and service arguments cannot both be NULL. 

15894 The flags argument is a flag that changes the default actions of the function. By default the fully- 

15895 qualified domain name (FQDN) for the host is returned, but: 

15896 • If the flag bit NI_NOFQDN is set, only the node name portion of the FQDN shall be returned 

15897 for local hosts. 

15898 • If the flag bit NI_NUMERICHOST is set, the numeric form of the host's address shall be 

15899 returned instead of its name, under all circumstances. 

15900 • If the flag bit NI_NAMEREQD is set, an error shall be returned if the host's name cannot be 

15901 located. 

15902 • If the flag bit NI_NUMERICSERV is set, the numeric form of the service address shall be 

15903 returned (for example, its port number) instead of its name, under all circumstances. 

15904 • If the flag bit NI_DGRAM is set, this indicates that the service is a datagram service 

15905 (SOCK_DGRAM). The default behavior shall assume that the service is a stream service 

15906 (SOCK_STRE AM). 

15907 Notes: 

15908 1. The two NI_NUMERICxxx flags are required to support the -n flag that many 

15909 commands provide. 
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2. The NI_DGRAM flag is required for the few AF_INET and AF_INET6 port 
numbers (for example, 512-514) that represent different services for UDP and 
TCP. 


The getnameinfo( ) function shall be thread-safe. 

RETURN VALUE 

A zero return value for getnameinfo() indicates successful completion; a non-zero return value 
indicates failure. 

Upon successful completion, getnameinfo() shall return the node and service names, if requested, 
in the buffers provided. The returned names are always null-terminated strings, and may be 
truncated if the actual values are longer than can be stored in the buffers provided. 


ERRORS 

The getnameinfo( ) function shall fail and return the corresponding value if: 

[EAI_AGAIN] The name could not be resolved at this time. Future attempts may succeed. 

[EAI_BADFLAGS] 

The/fays had an invalid value. 

[EAI_FAIL] A non-recoverable error occurred. 

[EAI_FAMILY] The address family was not recognized or the address length was invalid for 
the specified family. 

[EAI_MEMORY] There was a memory allocation failure. 

[EAI_NONAME] The name does not resolve for the supplied parameters. 

NI_NAMEREQD is set and the host's name cannot be located, or both 
nodename and servname were null. 

[EAI_SYSTEM] A system error occurred. The error code can be found in errno. 

EXAMPLES 

None. 

APPLICATION USAGE 

If the returned values are to be used as part of any further name resolution (for example, passed 
to getaddrinfo()), applications shall either provide buffers large enough to store any result 
possible on the system or shall check for truncation and handle that case appropriately. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

getaddrinfo(), getservbyname (), getservbyport(), inet_ntop(), socket(), the System Interface 
Definitions volume of IEEE Std. 1003.1-200x, <netdb.h>, <sys/socket.h> 

CHANGE HISTORY 

First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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15948 NAME 

15949 getnetbyaddr — network database functions 

15950 SYNOPSIS 

15951 tinclude <netdb.h> 

15952 struct netent *getnetbyaddr(uint32_t net, int type); 

15953 DESCRIPTION 

15954 Refer to endnetent (). 
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15955 NAME 

15956 getnetbyname — network database functions 

15957 SYNOPSIS 

15958 tinclude <netdb.h> 

15959 struct netent *getnetbyname (const char 

15960 DESCRIPTION 

15961 Refer to endnetent (). 


* name) ; 
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15962 NAME 

15963 getnetent — network database functions 

15964 SYNOPSIS 

15965 tinclude <netdb.h> 

15966 struct netent *getnetent (void) ; 

15967 DESCRIPTION 

15968 Refer to endnetent (). 
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15969 NAME 

15970 getopt, optarg, opterr, optind, optopt — command option parsing 

15971 SYNOPSIS 

15972 #include <unistd.h> 

15973 int getopt (int argc, char * const argv[] , const char * optstring) ; 

15974 extern char *optarg; 

15975 extern int optind, opterr, optopt; 

15976 DESCRIPTION 

15977 The getopt () function is a command-line parser that can be used by applications that follow 

15978 Utility Syntax Guidelines 3, 4, 5, 6, 7, 9, and 10 in the System Interface Definitions volume of I 

15979 IEEE Std. 1003.1-200x, Section 12.2, Utility Syntax Guidelines. The remaining guidelines are not I 

15980 addressed by getopt () and are the responsibility of the application. I 

15981 The parameters argc and argv are the argument count and argument array as passed to main () 

15982 (see exec). The argument optstring is a string of recognized option characters; if a character is 

15983 followed by a colon, the option takes an argument. All option characters allowed by Utility 

15984 Syntax Guideline 3 are allowed in optstring. The implementation may accept other characters as 

15985 an extension. 

15986 The variable optind is the index of the next element of the argv[] vector to be processed. It is 

15987 initialized to 1 by the system, and getopt () updates it when it finishes with each element of 

15988 argv[ ]. When an element of argv[] contains multiple option characters, it is unspecified how 

15989 getopt () determines which options have already been processed. 

15990 The getopt () function shall return the next option character (if one is found) from argv that 

15991 matches a character in optstring, if there is one that matches. If the option takes an argument, 

15992 getopt () shall set the variable optarg to point to the option-argument as follows: 

15993 1. If the option was the last character in the string pointed to by an element of argv, then 

15994 optarg contains the next element of argv, and optind is incremented by 2. If the resulting 

15995 value of optind is greater than argc, this indicates a missing option-argument, and getopt () I 

15996 shall return an error indication. 

15997 2. Otherwise, optarg points to the string following the option character in that element of 

15998 argv, and optind is incremented by 1. 

15999 If, when getopt () is called: 

16000 argvfoptind] is a null pointer 

16001 *argv[optind] is not the character — 

16002 argvfoptind] points to the string " 

16003 getopt () shall return -1 without changing optind. If: 

16004 argvfoptind] points to the string "—" 

16005 getopt () shall return -1 after incrementing optind. 

16006 If getopt () encounters an option character that is not contained in optstring, it shall return the 

16007 question-mark (' ?') character. If it detects a missing option-argument, it shall return the colon 

16008 character (' :') if the first character of optstring was a colon, or a question-mark character (' ?') 

16009 otherwise. In either case, getopt () shall set the variable optopt to the option character that caused 

16010 the error. If the application has not set the variable opterr to 0 and the first character of optstring 

16011 is not a colon, getopt () shall also print a diagnostic message to stderr in the format specified for 

16012 the getopts utility. 
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The getopt( ) function need not be reentrant. A function that is not required to be reentrant is not 
required to be thread-safe. 

RETURN VALUE 

The getopt( ) function shall return the next option character specified on the command line. 

A colon (' :') shall be returned if getopt( ) detects a missing argument and the first character of 
optstring was a colon (' :'). 

A question mark (' ?') shall be returned if getopt() encounters an option character not in 
optstring or detects a missing argument and the first character of optstring was not a colon (' :'). 

Otherwise, getopt( ) shall return -1 when all command line options are parsed. 

ERRORS 

No errors are defined. 

EXAMPLES 

Parsing Command Line Options 

The following code fragment shows how you might process the arguments for a utility that can 
take the mutually-exclusive options a and b and the options / and o, both of which require 
arguments: 

#include <unistd.h> 
int 

main (int argc, char *argv[ ]) 

{ 

int c; 

int bflg, aflg, errflg; 
char *ifile; 
char *ofile; 
extern char *optarg; 
extern int optind, optopt; 

while ( (c = getopt(argc, argv, ":abf:o:")) != -1) { 

switch (c) { 

case 'a' : 

if (bflg) 

errflg++; 

else 

aflg++; 
break; 
case 'b' : 

if (aflg) 

errflg++; 
else { 

bflg++; 
bproc (); 

} 

break; 
case ' f' : 

ifile = optarg; 
break; 
case 'o' : 
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ofile = optarg; 
break; 

case ' : /* -f or -o without operand */ 

fprintf(stderr, 

"Option -%c requires an operand\n", optopt); 
errflg++; 
break; 

case '?': 


fprintf(stderr, 

"Unrecognized 


errflg++; 


option: 


-%c\n", optopt); 


if (errflg) { 

fprintf(stderr, "usage: . . . "); 

exit(2) ; 

} 

for ( ; optind < argc; optind++) { 

if (access(argv[optind] , R_OK)) { 


This code accepts any of the following as equivalent: 

cmd —ao arg path path 
cmd —a —o arg path path 
cmd —o arg —a path path 
cmd —a —o arg — path path 
cmd —a —oarg path path 
cmd —aoarg path path 

Checking Options and Arguments 

The following example parses a set of command line options and prints messages to standard 
output for each option and argument that it encounters. 

#include <unistd.h> 

#include <stdio.h> 

int c; 

char *filename; 

extern char *optarg; 

extern int optind, optopt, opterr; 

while ((c = getopt(argc, argv, ":abf:")) != -1) { 

switch (c) { 

case 'a': 

printf ("a is set\n"); 
break; 
case 'b': 

printf ("b is set\n"); 
break; 
case 'f : 

filename = optarg; 
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16109 printf ("filename is %s\n", filename); 

16110 break; 

16111 case 

16112 printf ("~%c without filename\n", optopt); 

16113 break; 

16114 case ' ?' : 

16115 printf ("unknown arg %c\n", optopt); 

16116 break; 

16117 } 

16118 } 

16119 Selecting Options from the Command Line 

16120 The following example selects the type of database routines the user wants to use based on the 

16121 Options argument. 

16122 #include <unistd.h> 

16123 tinclude <string.h> 

16124 

16125 char *Options = "hdbtl"; 

16126 

16127 int dbtype, i; 

16128 char c; 

16129 char *st; 

16130 

16131 dbtype = 0; 

16132 while ( (c = getopt (argc, argv. Options)) != —1) { 

16133 if ( (st = strchr (Options, c) ) != NULL) { 

16134 dbtype = st - Options; 

16135 break; 

16136 } 

16137 } 

16138 APPLICATION USAGE 

16139 The getopt () function is only required to support option characters included in Utility Syntax 

16140 Guideline 3. Many historical implementations of getopt () support other characters as options. 

16141 This is an allowed extension, but applications that use extensions are not maximally portable. 

16142 Note that support for multi-byte option characters is only possible when such characters can be 

16143 represented as type int. 

16144 RATIONALE 

16145 The optopt variable represents historical practice and allows the application to obtain the identity 

16146 of the invalid option. 

16147 The description has been written to make it clear that getopt (), like the getopts utility, deals with 

16148 option-arguments whether separated from the option by <blank> characters or not. Note that 

16149 the requirements on getopt () and getopts are more stringent than the Utility Syntax Guidelines. 

16150 The getopt () function shall return -1, rather than EOF, so that <stdio.h> is not required. 

16151 The special significance of a colon as the first character of optstring makes getopt () consistent 

16152 with the getopts utility. It allows an application to make a distinction between a missing 

16153 argument and an incorrect option letter without having to examine the option letter. It is true 

16154 that a missing argument can only be detected in one case, but that is a case that has to be 

16155 considered. 
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16156 FUTURE DIRECTIONS 

16157 None. 

16158 SEE ALSO 

16159 exec, the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h>, the 

16160 Commands and Utilities volume of IEEE Std. 1003.1-200x 

16161 CHANGE HISTORY 

16162 First released in Issue 1. 

16163 Derived from Issue 1 of the SVID. 

16164 Issue 4 

16165 The following changes are incorporated for alignment with the ISO POSIX-2 standard: 

16166 • The <unistd.h> header is added to the SYNOPSIS section and <stdio.h> is deleted. 

16167 • The type of argument argv is changed from char** to char*const[ ]. 

16168 • The integer optopt is added to the list of external data items. 

16169 • The DESCRIPTION is largely rewritten, without functional change, for alignment with the 

16170 ISO POSIX-2 standard, although the following differences should be noted: 

16171 — If the function detects a missing option-argument, it returns a colon (' :') and sets optopt 

16172 to the option character. 

16173 — The termination conditions under which getopt () returns -1 are extended. Also note that 

16174 the termination condition is explicitly -1, rather than the value of EOF. 

16175 • The EXAMPLES section is changed to illustrate the new functionality. 

16176 Issue 5 

16177 A note indicating that the getopt () function need not be reentrant is added to the DESCRIPTION. I 

16178 Issue 6 I 

16179 PASC Interpretation 1003.2 #150 is included. I 
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16180 NAME 

16181 getpeemame — get the name of the peer socket 

16182 SYNOPSIS 

16183 tinclude <sys/socket. h> 

16184 int getpeername (int socket, struct sockaddr * address, 

16185 socklen_t *address_len) ; 

16186 DESCRIPTION 

16187 The getpeername() function shall retrieve the peer address of the specified socket, store this 

16188 address in the sockaddr structure pointed to by the address argument, and store the length of this 

16189 address in the object pointed to by the address_len argument. 

16190 If the actual length of the address is greater than the length of the supplied sockaddr structure, 

16191 the stored address shall be truncated. 

16192 If the protocol permits connections by unbound clients, and the peer is not bound, then the value 

16193 stored in the object pointed to by address is unspecified. 

16194 RETURN VALUE 

16195 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 

16196 indicate the error. 

16197 ERRORS 


16198 

The getpeername() 

function shall fail if: 

16199 

[EBADF] 

The socket argument is not a valid file descriptor. 

16200 

[EFAULT] 

The address or address_len parameter cannot be accessed or written. 

16201 

[EINVAL] 

The socket has been shut down. 

16202 

[ENOTCONN] 

The socket is not connected or otherwise has not had the peer prespecified. 

16203 

[ENOTSOCK] 

The socket argument does not refer to a socket. 

16204 

[EOPNOTSUPP] 

The operation is not supported for the socket protocol. 

16205 

The getpeername () 

function may fail if: 

16206 

[ENOBUFS] 

Insufficient resources were available in the system to complete the call. 

16207 XSR 

[ENOSR] 

There were insufficient STREAMS resources available for the operation to 

16208 


complete. 

16209 EXAMPLES 


16210 

None. 



16211 APPLICATION USAGE 

16212 None. 

16213 RATIONALE 

16214 None. 

16215 FUTURE DIRECTIONS 

16216 None. 

16217 SEE ALSO 

16218 acceptO , bind (), getsocknameO , socketO , the System Interface Definitions volume of 

16219 IEEE Std. 1003.1-200x, <sys/socket.h> 
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16220 CHANGE HISTORY 

16221 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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16222 NAME 

16223 getpgid — get the process group ID for a process 

16224 Notes to Reviewers 

16225 This section with side shading will not appear in the final copy. - Ed. 

16226 This function or these functions are recommended to become mandatory parts of POSIX.l in the 

16227 next draft. 

16228 SYNOPSIS 

16229 xsi tinclude <unistd.h> 

16230 pid_t getpgid (pid_t pid) ; 

16231 


16232 DESCRIPTION 

16233 The getpgid () function shall return the process group ID of the process whose process ID is equal 

16234 to pid. If pid is equal to 0, getpgid () shall return the process group ID of the calling process. 

16235 RETURN VALUE 

16236 Upon successful completion, getpgid () shall return a process group ID. Otherwise, it shall return 

16237 (pid_t)-l and set errno to indicate the error. 


16238 ERRORS 

16239 The getpgid () function shall fail if: 


16240 

16241 

16242 


[EPERM] The process whose process ID is equal to pid is not in the same session as the 

calling process, and the implementation does not allow access to the process 
group ID of that process from the calling process. 


16243 


[ESRCEI] There is no process with a process ID equal to pid. 


16244 The getpgid () function may fail if: 

16245 [EINVAL] The value of the pid argument is invalid. 

16246 EXAMPLES 

16247 None. 

16248 APPLICATION USAGE 

16249 None. 

16250 RATIONALE 

16251 None. 

16252 FUTURE DIRECTIONS 

16253 None. 

16254 SEE ALSO 

16255 exec, fork (), getpgrp(), getpid(), getsid (), setpgid{), setsid (), the System Interface Definitions 

16256 volume of IEEE Std. 1003.1-200x, <unistd.h> 

16257 CHANGE HISTORY 

16258 First released in Issue 4, Version 2. 

16259 Issue 5 

16260 Moved from X/OPEN UNIX extension to BASE. 
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16261 NAME 

16262 getpgrp — get the process group ID of the calling process 

16263 SYNOPSIS 

16264 #include <unistd.h> 

16265 pid_t getpgrp (void) ; 

16266 DESCRIPTION 

16267 The getpgrp () function shall return the process group ID of the calling process. 

16268 RETURN VALUE 

16269 The getpgrp () function is always successful and no return value is reserved to indicate an error. 

16270 ERRORS 

16271 No errors are defined. 

16272 EXAMPLES 

16273 None. 

16274 APPLICATION USAGE 

16275 None. 

16276 RATIONALE 

16277 4.3 BSD provides a getpgrp () function that returns the process group ID for a specified process. 

16278 Although this function is used to support job control, all known job control shells always specify 

16279 the calling process with this function. Thus, the simpler System V getpgrp () suffices, and the 

16280 added complexity of the 4.3 BSD getpgrpO has been omitted from this volume of 

16281 IEEE Std. 1003.1-200x. 

16282 FUTURE DIRECTIONS 

16283 None. 

16284 SEE ALSO 

16285 exec, forkO, getpgidO, getpidO, getppidO, killO, setpgidO, setsid (), the System Interface 

16286 Definitions volume of IEEE Std. 1003.1-200x, <sys/types.h>, <unistd.h> 

16287 CHANGE HISTORY 

16288 First released in Issue 1. 

16289 Derived from Issue 1 of the SVID. 

16290 Issue 4 

16291 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

16292 XSI-conformant systems. 

16293 The <unistd.h> header is added to the SYNOPSIS section. 

16294 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

16295 • The argument list is explicitly defined as void. 

16296 Issue 6 

16297 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

16298 The following new requirements on POSIX implementations derive from alignment with the 

16299 Single UNIX Specification: 

16300 • The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 

16301 required for conforming implementations of previous POSIX specifications, it was not 

16302 required for UNIX applications. 
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16303 

16304 

16305 

16306 

16307 

16308 

16309 

16310 

16311 

16312 

16313 

16314 

16315 

16316 

16317 

16318 

16319 

16320 

16321 

16322 

16323 

16324 

16325 

16326 

16327 

16328 

16329 

16330 

16331 

16332 

16333 

16334 

16335 

16336 

16337 

16338 

16339 

16340 


NAME 

getpid — get the process ID 

SYNOPSIS 

#include <unistd.h> 
pid_t getpid(void); 

DESCRIPTION 

The getpid () function shall return the process ID of the calling process. 

RETURN VALUE 

The getpid () function is always successful and no return value is reserved to indicate an error. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

exec, fork (), getpgrp (), getppid (), kill (), setpgid (), setsid (), the System Interface Definitions volume 
of IEEE Std. 1003.1-200x, <sys/types.h>, <unistd.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 
XSI-conformant systems. 

The <unistd.h> header is added to the SYNOPSIS section. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The argument list is explicitly defined as void. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 
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16341 NAME 

16342 getpmsg — receive next message from a STREAMS file 

16343 SYNOPSIS 

16344 xsi tinclude <stropts.h> 

16345 int getpmsg (int fildes, struct strbuf *ctlptr, struct strbuf *dataptr, 

16346 int *bandp, int * flagsp) ; 

16347 

16348 DESCRIPTION 

16349 Refer to getmsg (). 
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16350 

16351 

16352 

16353 

16354 

16355 

16356 

16357 

16358 

16359 

16360 

16361 

16362 

16363 

16364 

16365 

16366 

16367 

16368 

16369 

16370 

16371 

16372 

16373 

16374 

16375 

16376 

16377 

16378 

16379 

16380 

16381 

16382 

16383 

16384 

16385 

16386 

16387 


NAME 

getppid — get the parent process ID 

SYNOPSIS 

#include <unistd.h> 
pid_t getppid(void); 

DESCRIPTION 

The getppid () function shall return the parent process ID of the calling process. 

RETURN VALUE 

The getppid () function is always successful and no return value is reserved to indicate an error. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

exec, fork{), getpgid(), getpgrp{), getpid(), kill(), setpgid(), setsid (), the System Interface 
Definitions volume of IEEE Std. 1003.1-200x, <sys/types.h>, <unistd.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 
XSI-conformant systems. 

The <unistd.h> header is added to the SYNOPSIS section. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The argument list is explicitly defined as void. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 
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16388 NAME 

16389 getpriority, setpriority — get or set the nice value 

16390 SYNOPSIS 

16391 xsi tinclude <sys/resource.h> 

16392 int getpriority (int which, id_t who); 

16393 int setpriority (int which, id_t who, int value); 

16394 

16395 DESCRIPTION 

16396 The getpriority () function obtains the nice value of a process, process group, or user. The 

16397 setpriority () function sets the nice value of a process, process group, or user to volne+ {NZERO}. 

16398 Target processes are specified by the values of the ivliich and zvho arguments. The ivliich 

16399 argument may be one of the following values: PRIO_PROCESS, PRIO_PGRP, or PRIO_USER, 

16400 indicating that the zvho argument is to be interpreted as a process ID, a process group ID, or an 

16401 effective user ID, respectively. A 0 value for the zvho argument specifies the current process, 

16402 process group, or user. 

16403 The nice value set with setpriority () shall be applied to the process. If the process is multi- 

16404 threaded, the nice value shall affect all system scope threads in the process. 

16405 If more than one process is specified, getpriority () shall return value {NZERO} less than the 

16406 lowest nice value pertaining to any of the specified processes, and setpriority () sets the nice 

16407 values of all of the specified processes to vahie+ {NZERO}. 

16408 The default nice value is {NZERO}; lower nice values cause more favorable scheduling. While 

16409 the range of valid nice values is [0,{NZERO}*2 -1], implementations may enforce more 

16410 restrictive limits. If vahie+ {NZERO} is less than the system's lowest supported nice value, 

16411 setpriority () sets the nice value to the lowest supported value; if value + {NZERO} is greater than 

16412 the system's highest supported nice value, setpriority () sets the nice value to the highest 

16413 supported value. 

16414 Only a process with appropriate privileges can lower its nice value. 

16415 ps i tps Any processes or threads using SCHED_FIFO or SCHED_RR are unaffected by a call to 

16416 setpriority (). This is not considered an error. 

16417 The effect of changing the nice value may vary depending on the process-scheduling algorithm 

16418 in effect. 

16419 Because getpriority () can return the value -1 on successful completion, it is necessary to set errno 

16420 to 0 prior to a call to getpriority (). If getpriority () returns the value -1, then errno can be checked 

16421 to see if an error occurred or if the value is a legitimate nice value. 

16422 RETURN VALUE 

16423 Upon successful completion, getpriority () shall return an integer in the range from -{NZERO} to 

16424 {NZERO}-l. Otherwise, -1 shall be returned and errno set to indicate the error. 

16425 Upon successful completion, setpriority () shall return 0; otherwise, -1 shall be returned and errno 

16426 set to indicate the error. 

16427 ERRORS 

16428 The getpriority () and setpriority () functions shall fail if: 

16429 [ESRCH] No process could be located using the zvhich and zvho argument values 

16430 specified. 
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16431 [EINVAL] The value of the which argument was not recognized, or the value of the who 

16432 argument is not a valid process ID, process group ID, or user ID. 

16433 In addition, setpriority () may fail if: 


16434 

16435 

16436 


[EPERM] A process was located, but neither the real nor effective user ID of the 

executing process match the effective user ID of the process whose nice value 
is being changed. 


16437 [EACCES] A request was made to change the nice value to a lower numeric value and 

16438 the current process does not have appropriate privileges. 

16439 EXAMPLES 

16440 Using getpriority() 

16441 The following example returns the current scheduling priority for the process ID returned by the 

16442 call to getpid (). 

16443 #include <sys/resource . h> 

16444 

16445 int which = PRIO_PROCESS; 

16446 id_t pid; 

16447 int ret; 

16448 pid = getpid (); 

16449 ret = getpriority (which, pid) ; 


16450 Using setpriority( ) 

16451 The following example sets the priority for the current process ID to -20. 

16452 #include <sys/resource . h> 

16453 

16454 int which = PRIO_PROCESS; 

16455 id_t pid; 

16456 int priority = -20; 

16457 int ret; 

16458 pid = getpid (); 

16459 ret = setpriority (which, pid, priority) ; 

16460 APPLICATION USAGE 

16461 The getpriority () and setpriority () functions work with an offset nice value (nice value 

16462 -{NZERO}). The nice value is in the range [0,2*{NZERO} -1], while the return value for 

16463 getpriority () and the third parameter for setpriority () are in the range [-{NZERO},jNZERO} -1]. 

16464 RATIONALE 

16465 None. 

16466 FUTURE DIRECTIONS 

16467 None. 

16468 SEE ALSO 

16469 nice( ), sched_get jpriority_max (), sched_setschednler( ), the System Interface Definitions volume of 

16470 IEEE Std. 1003.1-200x, <sys/resource.h> 
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16471 CHANGE HISTORY 

16472 First released in Issue 4, Version 2. 

16473 Issue 5 

16474 Moved from X/OPEN UNIX extension to BASE. 

16475 The DESCRIPTION is reworded in terms of the nice value rather than priority to avoid confusion I 

16476 with functionality in the POSIX Realtime Extension. 
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16477 NAME 

16478 getprotobyname — network protocol database functions 

16479 SYNOPSIS 

16480 tinclude <netdb.h> 

16481 struct protoent *getprotobyname (const char 

16482 DESCRIPTION 

16483 Refer to en dp ro toen t (). 


* name) ; 
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16484 NAME 

16485 getprotobynumber — network protocol database functions 

16486 SYNOPSIS 

16487 #include <netdb.h> 

16488 struct protoent *getprotobynumber (int proto); 

16489 DESCRIPTION 

16490 Refer to en dp ro toen t (). 
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16491 NAME 

16492 getprotoent — network protocol database functions 

16493 SYNOPSIS 

16494 #include <netdb.h> 

16495 struct protoent *getprotoent (void) ; 

16496 DESCRIPTION 

16497 Refer to en dp ro toen t (). 
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16498 NAME 

16499 getpwent — get user database entry 

16500 SYNOPSIS 

16501 xsi #include <pwd.h> 

16502 struct passwd *getpwent (void) ; 

16503 

16504 DESCRIPTION 

16505 Refer to endpzvent (). 
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16506 NAME 

16507 getpwnam, getpwnam_r — search user database for a name 

16508 SYNOPSIS 

16509 tinclude <pwd.h> 

16510 struct passwd *getpwnam(const char * name) } 

16511 TSF int getpwnam_r (const char *nam, struct passwd *pwd, char * buffer , 

16512 size_t bufsize, struct passwd ** result) ; 

16513 

16514 DESCRIPTION 

16515 The getpwnam ( ) function shall search the user database for an entry with a matching name. 

16516 The getpzvnam ( ) function need not be reentrant. A function that is not required to be reentrant is 

16517 not required to be thread-safe. 

16518 tsf The getpwnam_r( ) function updates the passwd structure pointed to by pzvd and stores a pointer 

16519 to that structure at the location pointed to by result. The structure shall contain an entry from 

16520 the user database with a matching name. Storage referenced by the structure is allocated from 

16521 the memory provided with the buffer parameter, which is bufsize characters in size. The 

16522 maximum size needed for this buffer can be determined with the {_SC_GETPW_R_SIZE_MAX} 

16523 sysconf( ) parameter. A NULL pointer shall be returned at the location pointed to by result on 

16524 error or if the requested entry is not found. 

16525 Applications wishing to check for error situations should set errno to 0 before calling 

16526 getpwnam{ ). If getpzvnam () returns a null pointer and errno is non-zero, an error occurred. 

16527 RETURN VALUE 

16528 The getpwnam() function shall return a pointer to a struct passwd with the structure as defined 

16529 in <pwd.h> with a matching entry if found. A null pointer shall be returned if the requested 

16530 man entry is not found, or an error occurs. On error, errno shall be set to indicate the error. 

16531 The return value may point to a static area which is overwritten by a subsequent call to 

16532 getpzvent( ), getpzvnam (), or getpzvuid (). 

16533 tsf If successful, the getpzvnam_r( ) function shall return zero; otherwise, an error number shall be 

16534 returned to indicate the error. 

16535 ERRORS 

16536 man The getpzvnam( ) and getpzvnam_r( )functions may fail if: 

16537 man [EIO] An I/O error has occurred. 

16538 man [EINTR] A signal was caught during getpzvnam ( ). 

16539 man [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 

16540 man [ENFILE] The maximum allowable number of files is currently open in the system. 

16541 tsf The getpzvnam_r( ) function may fail if: 

16542 tsf [ERANGE] Insufficient storage was supplied via buffer and bufsize to contain the data to 

16543 be referenced by the resulting passwd structure. 
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16544 

16545 

16546 

16547 

16548 

16549 

16550 

16551 

16552 

16553 

16554 

16555 

16556 

16557 

16558 

16559 

16560 

16561 

16562 

16563 

16564 

16565 

16566 

16567 

16568 

16569 

16570 

16571 

16572 

16573 

16574 

16575 

16576 

16577 

16578 

16579 

16580 

16581 

16582 

16583 

16584 

16585 

16586 


EXAMPLES 


Getting an Entry for the Login Name 

The following example uses the getlogin () function to return the name of the user who logged in; 
this information is passed to the getpwnam( ) function to get the user database entry for that user. 


#include 

#include 

#include 

#include 

#include 


<sys/types.h> 
<pwd.h> 
<unistd.h> 
<stdio.h> 
<stdlib.h> 


char *lgn; 
struct passwd *pw; 

if ((lgn = getlogin ()) == NULL || (pw = getpwnam (lgn)) == NULL) { 
fprintf (stderr, "Get of user information failed.\n"); exit (1); 

} 


APPLICATION USAGE 

Three names associated with the current process can be determined: getpwuid(geteuid()) returns 
the name associated with the effective user ID of the process; getlogin () returns the name 
associated with the current login activity; and getpivuid(gehdd()) returns the name associated 
with the real user ID of the process. 

The getpivnam_r() function is thread-safe and shall return values in a user-supplied buffer 
instead of possibly using a static data area that may be overwritten by each call. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

getpzvuid(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <limits.h>, 
<pwd.h>, <sys/types.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from System V Release 2.0. 

Issue 4 

The DESCRIPTION is clarified. 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 
XSI-conformant systems. 

The last sentence in the RETURN VALUE section, indicating that errno is set on error, is marked 
as an extension. 

The errors [EIO], [EINTR], [EMFILE], and [ENFILE] are marked as extensions. 

The APPLICATION USAGE section is expanded to warn about possible reuses of the area used 
to pass the return value, and to indicate how applications should check for errors. 


System Interfaces, Issue 6 


521 



getpwnam() 


System Interfaces 


16587 

16588 

16589 

16590 

16591 

16592 

16593 

16594 

16595 

16596 

16597 

16598 

16599 

16600 
16601 

16602 

16603 

16604 

16605 

16606 

16607 

16608 

16609 

16610 


The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The type of argument name is changed from char 51 ' to const char*. 

Issue 5 

Normative text previously in the APPLICATION USAGE section is moved to the RETURN 
VALUE section. 

The getpwnam_r () function is included for alignment with the POSIX Threads Extension. 

A note indicating that the getpzvnam() function need not be reentrant is added to the 
DESCRIPTION. 


Issue 6 

The getpzvnam_r{) function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS 
option. 

The Open Group corrigenda item U028/3 has been applied correcting text in the DESCRIPTION 
describing matching the name. 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• In the RETURN VALUE section, the requirement to set errno on error is added. 

• The [EMFILE], [ENFILE], and [ENXIO] optional error conditions are added. 

The APPLICATION USAGE section is updated to include a note on the thread-safe function and 
its avoidance of possibly using a static data area. 
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16611 

16612 

16613 

16614 

16615 

16616 

16617 

16618 

16619 

16620 

16621 

16622 

16623 

16624 

16625 

16626 

16627 

16628 

16629 

16630 

16631 

16632 

16633 

16634 

16635 

16636 

16637 

16638 

16639 

16640 

16641 

16642 

16643 

16644 

16645 

16646 

16647 

16648 


NAME 

getpwuid, getpwuid_r — search user database for a user ID 

SYNOPSIS 

#include <pwd.h> 

struct passwd *getpwuid(uid_t uid) ; 
tsf int getpwuid_r (uid_t uid, struct passwd *pwd, char * buffer , 

size_t bufsize, struct passwd **result); 


DESCRIPTION 

The getpzvnid( ) function shall search the user database for an entry with a matching uid. 

The getpividd() function need not be reentrant. A function that is not required to be reentrant is 
not required to be thread-safe. 

tsf The getpivuid_r( ) function updates the passwd structure pointed to by pivd and stores a pointer 
to that structure at the location pointed to by resirit. The structure shall contain an entry from 
the user database with a matching idd. Storage referenced by the structure is allocated from the 
memory provided with the buffer parameter, which is bufsize characters in size. The maximum 
size needed for this buffer can be determined with the {_SC_GETPW_R_SIZE_MAX} sysconf () 
parameter. A NULL pointer shall be returned at the location pointed to by residt on error or if the 
requested entry is not found. 

Applications wishing to check for error situations should set errno to 0 before calling getpividd(). 
If getpwuid () returns a null pointer and errno is set to non-zero, an error occurred. 

RETURN VALUE 

The getpiv:dd() function shall return a pointer to a struct passwd with the structure as defined in 
<pwd.h> with a matching entry if found. A null pointer shall be returned if the requested entry 
man is not found, or an error occurs. On error, errno shall be set to indicate the error. 

The return value may point to a static area which is overwritten by a subsequent call to 
getpzvent( ), getpwnam(), or getpiv:dd (). 

tsf If successful, the getpzvidd_r() function shall return zero; otherwise, an error number shall be 
returned to indicate the error. 

ERRORS 

man The getpiv:dd( ) and getpwuid_r () functions may fail if: 

man [EIO] An I/O error has occurred. 

man [EINTR] A signal was caught during getpzvuid (). 

man [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 

man [ENFILE] The maximum allowable number of files is currently open in the system. 

tsf The getpividd_r( ) function may fail if: 

tsf [ERANGE] Insufficient storage was supplied via buffer and bufsize to contain the data to 

be referenced by the resulting passwd structure. 
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16649 

16650 

16651 

16652 

16653 

16654 

16655 

16656 

16657 

16658 

16659 

16660 
16661 
16662 

16663 

16664 

16665 

16666 

16667 

16668 

16669 

16670 

16671 

16672 

16673 

16674 

16675 

16676 

16677 

16678 

16679 

16680 
16681 
16682 

16683 

16684 

16685 

16686 

16687 

16688 

16689 

16690 

16691 


EXAMPLES 

Getting an Entry for the Root User 

The following example gets the user database entry for the user with user ID 0 (root). 

tinclude <sys/types.h> 
tinclude <pwd.h> 

uid_t id = 0; 
struct passwd *pwd; 

pwd = getpwuid (id); 

Finding the Name for the Effective User ID 

The following example defines pzvs as a pointer to a structure of type passwd, which is used to 
store the structure pointer returned by the call to the getpivnid( ) function. The geteuid() function 
shall return the effective user ID of the calling process; this is used as the search criteria for the 
getpividd() function. The call to getpwuid() shall return a pointer to the structure containing that 
user ID value. 

tinclude <unistd.h> 

#include <sys/types.h> 
tinclude <pwd.h> 

struct passwd *pws; 

pws = getpwuid(geteuid()) ; 

Finding an Entry in the User Database 

The following example uses getpzvidd() to search the user database for a user ID that was 
previously stored in a stat structure, then prints out the user name if it is found. If the user is not 
found, the program prints the numeric value of the user ID for the entry. 

#include <sys/types.h> 

#include <pwd.h> 

#include <stdio.h> 

struct stat statbuf; 
struct passwd *pwd; 

if ((pwd = getpwuid (statbuf.st_uid)) != NULL) 

printf (" %-8.8s", pwd->pw_name) ; 

else 

printf (" %-8d", statbuf.st_uid); 

APPLICATION USAGE 

Three names associated with the current process can be determined: getpzvidd(geteidd()) returns 
the name associated with the effective user ID of the process; getlogin() returns the name 
associated with the current login activity; and getpiv:dd(gehdd()) returns the name associated 
with the real user ID of the process. 

The getpividd_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 
of possibly using a static data area that may be overwritten by each call. 
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16692 

16693 

16694 

16695 

16696 

16697 

16698 

16699 

16700 

16701 

16702 

16703 

16704 

16705 

16706 

16707 

16708 

16709 

16710 

16711 

16712 

16713 

16714 

16715 

16716 

16717 

16718 

16719 

16720 

16721 

16722 

16723 

16724 

16725 

16726 

16727 

16728 

16729 

16730 

16731 

16732 


RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

getpwnam(), geteuid(), getnid(), getlogin(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <limits.h>, <pwd.h>, <sys/types.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from System V Release 2.0. 

Issue 4 

The DESCRIPTION is clarified. 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 
XSI-conformant systems. 

The last sentence in the RETURN VALUE section, indicating that errno is set on error, is marked 
as an extension. 

The errors [EIO], [EINTR], [EMFILE], and [ENFILE] are marked as extensions. 

A note is added to the APPLICATION USAGE section indicating how an application should 
check for errors. 


Issue 5 

Normative text previously in the APPLICATION USAGE section is moved to the RETURN 
VALUE section. 

The getpzvidd_r( ) function is included for alignment with the POSIX Threads Extension. 

A note indicating that the getpivuid() function need not be reentrant is added to the 
DESCRIPTION. 


Issue 6 

The getpwuid_r( ) function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS 
option. 

The Open Group corrigenda item U028/3 has been applied correcting text in the DESCRIPTION 
describing matching the uid. 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• In the RETURN VALUE section, the requirement to set errno on error is added. 

• The [EIO], [EINTR], [EMFILE], and [ENFILE] optional error conditions are added. 

The APPLICATION USAGE section is updated to include a note on the thread-safe function and 
its avoidance of possibly using a static data area. 
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16733 NAME 

16734 getrlimit, setrlimit — control maximum resource consumption 

16735 SYNOPSIS 

16736 XSI 

16737 

16738 

16739 

16740 DESCRIPTION 

16741 Limits on the consumption of a variety of resources by the calling process may be obtained with 

16742 getrlimit () and set with setrlimit (). 

16743 Each call to either getrlimit () or setrlimit () identifies a specific resource to be operated upon as 

16744 well as a resource limit. A resource limit is represented by an rlimit structure. The rlim_cur 

16745 member specifies the current or soft limit and the rlim_max member specifies the maximum or 

16746 hard limit. Soft limits may be changed by a process to any value that is less than or equal to the 

16747 hard limit. A process may (irreversibly) lower its hard limit to any value that is greater than or 

16748 equal to the soft limit. Only a process with appropriate privileges can raise a hard limit. Both 

16749 hard and soft limits can be changed in a single call to setrlimit () subject to the constraints 

16750 described above. 


#include <sys/resource.h> 

int getrlimit(int resource, struct rlimit *rlp ); 

int setrlimit(int resource, const struct rlimit *rlp ); 


16751 

16752 

16753 

16754 

The value RLIM_INFINITY, defined in <sys/resource.h>, shall be considered to be larger than 
any other limit value. If a call to getrlimit () returns RLIM_INFINITY for a resource, it means the 
implementation shall not enforce limits on that resource. Specifying RLIM_INFINITY as any 
resource limit value on a successful call to setrlimit () inhibits enforcement of that resource limit. 

16755 

The following resources are defined: 

16756 

16757 

16758 

RLIMIT_CORE 

This is the maximum size of a core file in bytes that may be created by a 
process. A limit of 0 shall prevent the creation of a core file. If this limit is 
exceeded, the writing of a core file shall terminate at this size. 

16759 

16760 

16761 

16762 

RLIMIT_CPU 

This is the maximum amount of CPU time in seconds used by a process. 
If this limit is exceeded, SIGXCPU shall be generated for the process. If 
the process is catching or ignoring SIGXCPU, or all threads belonging to 
that process are blocking SIGXCPU, the behavior is unspecified. 

16763 

16764 

RLIMIT_DATA 

This is the maximum size of a process' data segment in bytes. If this limit 
is exceeded, the malloc () function shall fail with errno set to [ENOMEM], 

16765 

16766 

16767 

16768 

16769 

16770 

RLIMIT_FSIZE 

This is the maximum size of a file in bytes that may be created by a 
process. If a write or truncate operation would cause this limit to be 
exceeded, SIGXFSZ shall be generated for the thread. If the thread is 
blocking, or the process is catching or ignoring SIGXFSZ, continued 
attempts to increase the size of a file from end-of-file to beyond the limit 
shall fail with errno set to [EFBIG]. 

16771 

16772 

16773 

16774 

16775 

RLIMIT_NOFILE 

This is a number one greater than the maximum value that the system 
may assign to a newly-created descriptor. If this limit is exceeded, 
functions that allocate new file descriptors may fail with errno set to 
[EMFILE]. This limit constrains the number of file descriptors that a 
process may allocate. 

16776 

16777 

16778 

RLIMIT_STACK 

This is the maximum size of a process' stack in bytes. The 
implementation does not automatically grow the stack beyond this limit. 
If this limit is exceeded, SIGSEGV shall be generated for the thread. If the 
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16779 

16780 

16781 

16782 

16783 

16784 

16785 

16786 

16787 

16788 

16789 

16790 

16791 

16792 

16793 

16794 

16795 

16796 

16797 

16798 

16799 

16800 
16801 

16802 

16803 

16804 

16805 

16806 

16807 

16808 

16809 

16810 
16811 

16812 

16813 

16814 

16815 

16816 

16817 

16818 
16819 


thread is blocking SIGSEGV, or the process is ignoring or catching 
SIGSEGV and has not made arrangements to use an alternate stack, the 
disposition of SIGSEGV shall be set to SIG_DFL before it is generated. 

RLIMIT_AS This is the maximum size of a process' total available memory, in bytes. If 

this limit is exceeded, the malloc() and nimap () functions shall fail with 
errno set to [ENOMEM]. In addition, the automatic stack growth fails 
with the effects outlined above. 

When using the getrlimit( ) function, if a resource limit can be represented correctly in an object 
of type rlim_t, then its representation is returned; otherwise, if the value of the resource limit is 
equal to that of the corresponding saved hard limit, the value returned shall be 
RLIM_SAVED_MAX; otherwise, the value returned shall be RLIM_SAVED_CUR. 

When using the setr limit () function, if the requested new limit is RLIM_INFINITY, the new limit 
shall be "no limit"; otherwise, if the requested new limit is RLIM_SAVED_MAX, the new limit 
shall be the corresponding saved hard limit; otherwise, if the requested new limit is 
RLIM_SAVED_CUR, the new limit shall be the corresponding saved soft limit; otherwise, the 
new limit shall be the requested value. In addition, if the corresponding saved limit can be 
represented correctly in an object of type rlim_t then it shall be overwritten with the new limit. 

The result of setting a limit to RLIM_SAVED_MAX or RLIM_SAVED_CUR is unspecified unless 
a previous call to getrlimit () returned that value as the soft or hard limit for the corresponding 
resource limit. 

The determination of whether a limit can be correctly represented in an object of type rlim_t is 
implementation-dependent. For example, some implementations permit a limit whose value is 
greater than RLIM_INFINITY and others do not. 

The exec family of functions also cause resource limits to be saved. 

RETURN VALUE 

Upon successful completion, getrlimit () and setrlimit() shall return 0. Otherwise, these functions 
shall return -1 and set errno to indicate the error. 

ERRORS 

The getrlimit () and setrlimit( ) functions shall fail if: 

[EINVAL] An invalid resource was specified; or in a setrlimit() call, the new rlimjcur 

exceeds the new rlimjnax. 

[EPERM] The limit specified to setrlimit( ) would have raised the maximum limit value, 

and the calling process does not have appropriate privileges. 

The setr limit ( ) function may fail if: 

[EINVAL] The limit specified cannot be lowered because current usage is already higher 

than the limit. 

EXAMPLES 

None. 

APPLICATION USAGE 

If a process attempts to set the hard limit or soft limit for RLIMIT_NOFILE to less than the value 
of j_POSIX_OPEN_MAX[ from <limits.h>, unexpected behavior may occur. 
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16820 RATIONALE 

16821 None. 

16822 FUTURE DIRECTIONS 

16823 None. 

16824 SEE ALSO 

16825 exec, fork (), malloc(), open(), sigaltstack(), sysconf(), ulimit(), the System Interface Definitions 

16826 volume of IEEE Std. 1003.1-200x, <stropts.h>, <sys/resource.h> 

16827 CHANGE HISTORY 

16828 First released in Issue 4, Version 2. 

16829 Issue 5 

16830 Moved from X/OPEN UNIX extension to BASE and an APPLICATION USAGE section is added. 

16831 Large File Summit extensions are added. 
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16832 NAME 

16833 getrusage — get information about resource utilization 

16834 SYNOPSIS 

16835 xsi tinclude <sys/resource . h> 

16836 int getrusage (int who, struct rusage * r_usage) ; 

16837 

16838 DESCRIPTION 

16839 The getrnsage( ) function provides measures of the resources used by the current process or its 

16840 terminated and waited-for child processes. If the value of the zvho argument is RUSAGE_SELF, 

16841 information shall be returned about resources used by the current process. If the value of the zvho 

16842 argument is RUSAGE_CHILDREN, information shall be returned about resources used by the 

16843 terminated and waited-for children of the current process. If the child is never waited for (for 

16844 example, if the parent has SA_NOCLDWAIT set or sets SIGCHLD to SIG_IGN), the resource 

16845 information for the child process is discarded and not included in the resource information 

16846 provided by getrusage ( ). 

16847 The r_nsage argument is a pointer to an object of type struct rusage in which the returned 

16848 information is stored. 

16849 RETURN VALUE 

16850 Upon successful completion, getmsage( ) shall return 0; otherwise, -1 shall be returned and errno 

16851 set to indicate the error. 

16852 ERRORS 

16853 The getrnsage( ) function shall fail if: 

16854 [EINVAL] The value of the zvho argument is not valid. 

16855 EXAMPLES 

16856 Using getrusage( ) 

16857 The following example returns information about the resources used by the current process. 

16858 #include <sys/resource . h> 

16859 

16860 int who = RUSAGE_SELF; 

16861 struct rusage usage; 

16862 int ret; 

16863 ret = getrusage (who, Susage) ; 

16864 APPLICATION USAGE 

16865 None. 

16866 RATIONALE 

16867 None. 

16868 FUTURE DIRECTIONS 

16869 None. 

16870 SEE ALSO 

16871 exit(), sigaction(), time(), times (), zvait(), the System Interface Definitions volume of 

16872 IEEE Std. 1003.1-200x, <sys/resource.h> 
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16873 

16874 

16875 

16876 


CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 
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16877 NAME 

16878 gets — get a string from a stdin stream 

16879 SYNOPSIS 

16880 tinclude <stdio.h> 

16881 char *gets (char *s) ; 

16882 DESCRIPTION 

16883 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

16884 conflict between the requirements described here and the ISO C standard is unintentional. This I 

16885 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

16886 The gets() function shall read bytes from the standard input stream, stdin, into the array pointed 

16887 to by s, until a newline is read or an end-of-file condition is encountered. Any newline is 

16888 discarded and a null byte is placed immediately after the last byte read into the array. 

16889 cx The gets() function may mark the st_atime field of the file associated with stream for update. The 

16890 st_atime field shall be marked for update by the first successful execution of fgetc(), fgets(), 

16891 fread (), getc {), getchar (), gets( ),fscanf( ), or scanf( ) using stream that returns data not supplied by 

16892 a prior call to ungetc(). 

16893 RETURN VALUE 

16894 Upon successful completion, gets() shall return s. If the stream is at end-of-file, the end-of-file 

16895 indicator for the stream shall be set and gets( ) shall return a null pointer. If a read error occurs, 

16896 cx the error indicator for the stream shall be set, gets( ) shall return a null pointer and set errno to 

16897 indicate the error. 

16898 ERRORS 

16899 Refer to fgetc(). 

16900 EXAMPLES 

16901 Sending Prompts to Standard Output 

16902 The following example uses printf( ) calls to print a series of prompts for information the user 

16903 must enter from standard input. The /flush() calls force the output to standard output. The 

16904 /flush () function is used because standard output is usually buffered and the prompt may not 

16905 immediately be printed on the output or terminal. The gets() calls read strings from standard 

16906 input and place the results in variables, for use later in the program. 

16907 #include <stdio.h> 

16908 

16909 char user[100]; 

16910 char oldpasswd [ 100 ] ; 

16911 char newpasswd [ 100 ] ; 

16912 

16913 printf ("User name: "); 

16914 fflush (stdout); 

16915 gets (user) ; 

16916 printf ("Old password: "); 

16917 fflush (stdout); 

16918 gets (oldpasswd) ; 

16919 printf ("New password: "); 

16920 fflush (stdout); 

16921 gets (newpasswd) ; 
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16922 

16923 

16924 

16925 

16926 

16927 

16928 

16929 

16930 

16931 

16932 

16933 

16934 

16935 

16936 

16937 

16938 

16939 

16940 

16941 

16942 


APPLICATION USAGE 

Reading a line that overflows the array pointed to by s causes undefined results. The use of 
fgets() is recommended. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

/error(), fgets(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

<stdio.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

In the DESCRIPTION: 

• The text is changed to make it clear that the function reads bytes rather than (possibly multi¬ 
byte) characters. 

• The list of functions that may cause the st_atime field to be updated is revised. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 
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16943 NAME 

16944 getservbyname — network services database functions 

16945 SYNOPSIS 

16946 tinclude <netdb.h> 

16947 struct servent *getservbyname(const char *name, const char *proto ); 

16948 DESCRIPTION 

16949 Refer to endservent(). 
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16950 NAME 

16951 getservbyport — network services database functions 

16952 SYNOPSIS 

16953 tinclude <netdb.h> 

16954 struct servent *getservbyport (int port, const char *proto) ; 

16955 DESCRIPTION 

16956 Refer to endservent(). 
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16957 NAME 

16958 getservent — network services database functions 

16959 SYNOPSIS 

16960 tinclude <netdb.h> 

16961 struct servent *getservent (void) ; 

16962 DESCRIPTION 

16963 Refer to endservent(). 
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16964 NAME 

16965 getsid — get the process group ID of a session leader 

16966 SYNOPSIS 

16967 xsi #include <unistd.h> 

16968 pid_t getsid (pid_t pid) ; 

16969 


16970 DESCRIPTION 

16971 The getsid () function obtains the process group ID of the process that is the session leader of the 

16972 process specified by pid . If pid is (pid_t)0, it specifies the calling process. 

16973 RETURN VALUE 

16974 Upon successful completion, getsid() shall return the process group ID of the session leader of 

16975 the specified process. Otherwise, it shall return (pid_t)-l and set errno to indicate the error. 


16976 ERRORS 

16977 The getsid () function shall fail if: 


16978 

16979 

16980 


[EPERM] The process specified by pid is not in the same session as the calling process, 

and the implementation does not allow access to the process group ID of the 
session leader of that process from the calling process. 


16981 [ESRCEI] There is no process with a process ID equal to pid. 

16982 EXAMPLES 

16983 None. 

16984 APPLICATION USAGE 

16985 None. 

16986 RATIONALE 

16987 None. 

16988 FUTURE DIRECTIONS 

16989 None. 

16990 SEE ALSO 

16991 exec, fork (), getpid(), getpgid(), setpgid{), setsid (), the System Interface Definitions volume of 

16992 IEEE Std. 1003.1-200x, <unistd.h> 

16993 CHANGE HISTORY 

16994 First released in Issue 4, Version 2. 

16995 Issue 5 

16996 Moved from X/OPEN UNIX extension to BASE. 
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16997 NAME 

16998 getsockname — get the socket name 

16999 SYNOPSIS 

17000 tinclude <sys/socket.h> 

17001 int getsockname (int socket, struct sockaddr * address, 

17002 socklen_t * address_len) ; 

17003 DESCRIPTION 

17004 The getsockname() function shall retrieve the locally-bound name of the specified socket, store 

17005 this address in the sockaddr structure pointed to by the address argument, and store the length of 

17006 this address in the object pointed to by the address_len argument. 

17007 If the actual length of the address is greater than the length of the supplied sockaddr structure, 

17008 the stored address shall be truncated. 

17009 If the socket has not been bound to a local name, the value stored in the object pointed to by 

17010 address is unspecified. 

17011 RETURN VALUE 

17012 Upon successful completion, 0 shall be returned, the address argument shall point to the address 

17013 of the socket, and the address_len argument shall point to the length of the address. Otherwise, -1 

17014 shall be returned and errno set to indicate the error. 

17015 ERRORS 


17016 

The getsockname () 

function shall fail if: 

17017 

[EBADF] 

The socket argument is not a valid file descriptor. 

17018 

[EFAULT] 

The address or address_len parameter cannot be accessed or written. 

17019 

[ENOTSOCK] 

The socket argument does not refer to a socket. 

17020 

[EOPNOTSUPP] 

The operation is not supported for this socket's protocol. 

17021 

The getsockname () 

function may fail if: 

17022 

[EINVAL] 

The socket has been shut down. 

17023 

[ENOBUFS] 

Insufficient resources were available in the system to complete the function. 

17024 XSR 

[ENOSR] 

There were insufficient STREAMS resources available for the operation to 

17025 


complete. 

17026 EXAMPLES 


17027 

None. 



17028 APPLICATION USAGE 

17029 None. 

17030 RATIONALE 

17031 None. 

17032 FUTURE DIRECTIONS 

17033 None. 

17034 SEE ALSO 

17035 accept0, bind()r getpeernameO, socket0, the System Interface Definitions volume of 

17036 IEEE Std. 1003.1-200x, <sys/socket.h> 


System Interfaces, Issue 6 


537 




getsocknameO 


System Interfaces 


17037 CHANGE HISTORY 

17038 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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17039 NAME 

17040 getsockopt — get the socket options 

17041 SYNOPSIS 

17042 #include <sys/socket.h> 

17043 int getsockopt (int socket, int level, int option_name, 

17044 void *option_value, socklen_t * option_len) ; 

17045 DESCRIPTION 

17046 The getsockopt () function manipulates options associated with a socket. 

17047 The getsockopt () function shall retrieve the value for the option specified by the option_name 

17048 argument for the socket specified by the socket argument. If the size of the option value is greater 

17049 than option Jen, the value stored in the object pointed to by the option_valne argument shall be 

17050 silently truncated. Otherwise, the object pointed to by the option Jen argument shall be modified 

17051 to indicate the actual length of the value. 

17052 The level argument specifies the protocol level at which the option resides. To retrieve options at 

17053 the socket level, specify the level argument as SOL_SOCKET. To retrieve options at other levels, 

17054 supply the appropriate level identifier for the protocol controlling the option. For example, to 

17055 indicate that an option is interpreted by the TCP (Transmission Control Protocol), set level to 

17056 IPPROTO_TCP as defined in the <netinet/in.h> header. 

17057 The socket in use may require the process to have appropriate privileges to use the getsockopt () 

17058 function. 


17059 

17060 

The option_name argument specifies a single option to be retrieved. It can be one of the following 
values defined in <sys/socket.h>: 

17061 

17062 

SCLDEBUG 

Reports whether debugging information is being recorded. This option 
stores an int value. This is a Boolean option. 

17063 

17064 

SCLACCEPTCONN 

Reports whether socket listening is enabled. This option stores an int 
value. This is a Boolean option. 

17065 

17066 

17067 

SCLBROADCAST 

Reports whether transmission of broadcast messages is supported, if this 
is supported by the protocol. This option stores an int value. This is a 
Boolean option. 

17068 

17069 

17070 

SCLREUSEADDR 

Reports whether the rules used in validating addresses supplied to bind () 
should allow reuse of local addresses, if this is supported by the protocol. 
This option stores an int value. This is a Boolean option. 

17071 

17072 

SO_KEEP ALIVE 

Reports whether connections are kept active with periodic transmission 
of messages, if this is supported by the protocol. 

17073 

17074 

17075 


If the connected socket fails to respond to these messages, the connection 
is broken and processes writing to that socket are notified with a SIGPIPE 
signal. This option stores an int value. 

17076 


This is a Boolean option. 

17077 

17078 

17079 

17080 

17081 

17082 

17083 

SCLLINGER 

Reports whether the socket lingers on close () if data is present. If 
SO_LINGER is set, the system blocks the process during close () until it 
can transmit the data or until the end of the interval indicated by the 
IJinger member, whichever comes first. If SCLLINGER is not specified, 
and close {) is issued, the system handles the call in a way that allows the 
process to continue as quickly as possible. This option stores a linger 
structure. 
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17084 

17085 

17086 

17087 

17088 

17089 

17090 

17091 

17092 

17093 

17094 

17095 

17096 

17097 

17098 

17099 

17100 

17101 

17102 

17103 

17104 

17105 

17106 

17107 

17108 

17109 

17110 

17111 

17112 

17113 

17114 

17115 

17116 

17117 

17118 

17119 

17120 

17121 

17122 

17123 

17124 

17125 

17126 

17127 

17128 
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SCLOOBINLINE 


SCLSNDBUF 

SCLRCVBUF 

SCLERROR 


Reports whether the socket leaves received out-of-band data (data 
marked urgent) inline. This option stores an int value. This is a Boolean 
option. 

Reports send buffer size information. This option stores an int value. 

Reports receive buffer size information. This option stores an int value. 

Reports information about error status and clears it. This option stores an 
int value. 


SCLTYPE 

SCLDONTROUTE 


SCLRCVLOWAT 


SCLRCVTIMEO 


SCLSNDLOWAT 


SCLSNDTIMEO 


Reports the socket type. This option stores an int value. I 

Reports whether outgoing messages bypass the standard routing I 
facilities. The destination shall be on a directly-connected network, and I 
messages are directed to the appropriate network interface according to I 
the destination address. The effect, if any, of this option depends on what I 
protocol is in use. This option stores an int value. This is a Boolean I 
option. I 

Reports the minimum number of bytes to process for socket input I 
operations. The default value for SCLRCVLOWAT is 1. If I 
SO_RCVLOWAT is set to a larger value, blocking receive calls normally I 
wait until they have received the smaller of the low water mark value or I 
the requested amount. (They may return less than the low water mark if I 
an error occurs, a signal is caught, or the type of data next in the receive I 
queue is different than that returned; for example, out-of-band data.) I 
This option stores an int value. Note that not all implementations allow I 
this option to be retrieved. I 

Reports the timeout value for input operations. This option stores a I 
timeval structure with the number of seconds and microseconds I 
specifying the limit on how long to wait for an input operation to I 
complete. If a receive operation has blocked for this much time without I 
receiving additional data, it shall return with a partial count or errno set to I 
[E AG AIN] or [EWOULDBLOCK] if no data was received. The default for I 
this option is zero, which indicates that a receive operation shall not time I 
out. Note that not all implementations allow this option to be retrieved. I 

Reports the minimum number of bytes to process for socket output I 
operations. Non-blocking output operations shall process no data if flow I 
control does not allow the smaller of the send low water mark value or I 
the entire request to be processed. This option stores an int value. Note I 
that not all implementations allow this option to be retrieved. I 

Reports the timeout value specifying the amount of time that an output I 
function blocks because flow control prevents data from being sent. If a I 
send operation has blocked for this time, it shall return with a partial I 
count or with errno set to [EAGAIN] or [EWOULDBLOCK] if no data I 
were sent. The default for this option is zero, which indicates that a send I 
operation shall not time out. The option stores a timeval structure. Note I 
that not all implementations allow this option to be retrieved. I 


For Boolean options, a zero value indicates that the option is disabled and a non-zero value 
indicates that the option is enabled. 


Options at other protocol levels vary in format and name. 
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17130 

The socket in use may require the process to have appropriate privileges to use the getsockopt () 

1 

17131 

function. 


1 

17132 

RETURN VALUE 


1 

17133 

Upon successful completion, getsockopt () shall return 0; otherwise, -1 shall be returned and errno 

1 

17134 

set to indicate the error. 

1 

17135 

ERRORS 


1 

17136 

The getsockopt () function shall fail if: 

1 

17137 

[EBADF] 

The socket argument is not a valid file descriptor. 

1 

17138 

[EFAULT] 

The option_valne or option Jen parameter cannot be accessed or written. 

1 

17139 

[EINVAL] 

The specified option is invalid at the specified socket level. 

1 

17140 

[ENOPROTOOPT] 

1 

17141 


The option is not supported by the protocol. 

1 

17142 

[ENOTSOCK] 

The socket argument does not refer to a socket. 

1 

17143 

The getsockopt () function may fail if: 

1 

17144 

[EACCES] 

The calling process does not have the appropriate privileges. 

1 

17145 

[EINVAL] 

The socket has been shut down. 

1 

17146 

[ENOBUFS] 

Insufficient resources are available in the system to complete the function. 

1 

17147 

xsr [ENOSR] 

There were insufficient STREAMS resources available for the operation to 

1 

17148 


complete. 

1 

17149 

EXAMPLES 


1 

17150 

None. 


1 

17151 

APPLICATION USAGE 


1 

17152 

None. 


1 

17153 

RATIONALE 


1 

17154 

None. 


1 

17155 

FUTURE DIRECTIONS 


1 

17156 

None. 


1 

17157 

SEE ALSO 


1 

17158 

bind(), close(), endprotoent(), setsockopt(), socket (), the System Interface Definitions volume of 

1 

17159 

IEEE Std. 1003.1-200x, <sys/socket.h>, <netinet/in.h> 

1 

17160 

CHANGE HISTORY 


1 

17161 

First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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17162 NAME 

17163 getsubopt — parse suboption arguments from a string 

17164 SYNOPSIS 

17165 xsi tinclude <stdlib.h> 

17166 int getsubopt(char **optionp, char * const * tokens , char **valuep) ; 

17167 

17168 DESCRIPTION 

17169 The getsubopt () function parses suboption arguments in a flag argument that was initially parsed 

17170 by getopt(). The application shall ensure that these suboption arguments are separated by 

17171 commas and may consist of either a single token, or a token-value pair separated by an equal 

17172 sign. Because commas delimit suboption arguments in the option string, they are not allowed to 

17173 be part of the suboption arguments or the value of a suboption argument. Similarly, because the 

17174 equal sign separates a token from its value, the application shall ensure that a token does not 

17175 contain an equal sign. 

17176 The getsubopt( ) function takes the address of a pointer to the option argument string, a vector of 

17177 possible tokens, and the address of a value string pointer. If the option argument string at 

17178 *optionp contains only one suboption argument, getsubopt () updates *optionp to point to the null 

17179 at the end of the string. Otherwise, it isolates the suboption argument by replacing the comma 

17180 separator with a null, and updates *optionp to point to the start of the next suboption argument. 

17181 If the suboption argument has an associated value, getsubopt() updates *valuep to point to the 

17182 value's first character. Otherwise, it sets *valuep to a null pointer. 

17183 The token vector is organized as a series of pointers to strings. The end of the token vector is 

17184 identified by a null pointer. 

17185 When getsubopt( ) returns, if *valuep is not a null pointer, then the suboption argument processed 

17186 included a value. The calling program may use this information to determine whether the 

17187 presence or lack of a value for this suboption is an error. 

17188 Additionally, when getsubopt () fails to match the suboption argument with the tokens in the 

17189 tokens array, the calling program should decide if this is an error, or if the unrecognized option 

17190 should be passed on to another program. 

17191 RETURN VALUE 

17192 The getsubopt() function shall return the index of the matched token string, or -1 if no token 

17193 strings were matched. 

17194 ERRORS 

17195 No errors are defined. 


17196 EXAMPLES 


17197 

#include <stdio.h> 


17198 

#include <stdlib.h> 


17199 

int do_all; 


17200 

const char *type; 


17201 

int read_size; 


17202 

int write_size; 


17203 

int read_only; 


17204 

enum 


17205 

{ 


17206 

RO_OPTION = 0, 


17207 

RW_OPTION, 
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17208 

17209 

17210 

17211 

17212 

17213 

17214 

17215 

17216 

17217 

17218 

17219 

17220 

17221 

17222 

17223 

17224 

17225 

17226 

17227 

17228 

17229 

17230 

17231 

17232 

17233 

17234 

17235 

17236 

17237 

17238 

17239 

17240 

17241 

17242 

17243 

17244 

17245 

17246 

17247 

17248 

17249 

17250 

17251 

17252 

17253 

17254 

17255 

17256 

17257 

17258 


READ_SIZ E_OPTION, 

WRITE_SIZE_OPTION 

}; 

const char *mount_opts[] = 

{ 

[RO_OPTION] = "ro", 

[RW_OPTION] = "rw", 

[READ_SIZ E_OP TION] = "rsize", 

[WRITE_SIZE_OPTION] = "wsize" 

}; 

int 

main (int argc, char *argv[]) 

{ 

char *subopts, *value; 
int opt; 

while ((opt = getopt (argc, argv, "at:o:")) != -1) 

switch (opt) 

{ 

case 'a': 

do_all = 1; 
break; 
case 't' : 

type = optarg; 
break; 
case 'o': 

subopts = optarg; 
while (*subopts != ' ') 

switch (getsubopt (&subopts, mount_opts, Svalue)) 

{ 

case RO_OPTION: 

read_only = 1; 
break; 

case RW_OPTION: 

read_only = 0; 
break; 

case READ_SIZE_OPTION: 
if (value == NULL) 
abort (); 

read_size = atoi (value); 
break; 

case WRITE_SIZE_OPTION: 
if (value == NULL) 
abort (); 

write_size = atoi (value); 
break; 
default: 

/* Unknown suboption. */ 

printf ("Unknown suboption '%s'0, value); 
break; 


break; 
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17259 default: 

17260 abort () ; 

17261 } 

17262 /* Do the real work. */ 

17263 return 0; 

17264 } 

17265 Parsing Suboptions 

17266 The following example uses the getsnbopt() function to parse a value argument in the optarg 

17267 external variable returned by a call to getopt (). 

17268 #include <stdlib.h> 

17269 

17270 char *tokens[] = {"HOME", "PATH", "LOGNAME", (char *) NULL }; 

17271 char *value; 

17272 int opt, index; 

17273 while ((opt = getopt (argc, argv, "e:")) != -1) { 

17274 switch (opt) { 

17275 case ' e' : 

17276 while ((index = getsubopt (Soptarg, tokens, Svalue) ) != -1) { 

17277 switch (index) { 

17278 

17279 } 

17280 break; 

17281 

17282 } 

17283 } 

17284 

17285 APPLICATION USAGE 

17286 None. 

17287 RATIONALE 

17288 None. 

17289 FUTURE DIRECTIONS 

17290 None. 

17291 SEE ALSO 

17292 getopt (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

17293 CHANGE HISTORY 

17294 First released in Issue 4, Version 2. 

17295 Issue 5 

17296 Moved from X/OPEN UNIX extension to BASE. 
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17297 NAME 

17298 gettimeofday — get the date and time 

17299 SYNOPSIS 

17300 xsi tinclude <sys/time.h> 

17301 int gettimeofday (struct timeval *tp, void *tzp) ; 

17302 

17303 DESCRIPTION 

17304 The gettimeofday ( ) function obtains the current time, expressed as seconds and microseconds I 

17305 since the Epoch, and stores it in the timeval structure pointed to by tp. The resolution of the I 

17306 system clock is unspecified. 

17307 If tzp is not a null pointer, the behavior is unspecified. 

17308 RETURN VALUE 

17309 The gettimeofday ( ) function shall return 0 and no value shall be reserved to indicate an error. 

17310 ERRORS 

17311 No errors are defined. 

17312 EXAMPLES 

17313 None. 

17314 APPLICATION USAGE 

17315 None. 

17316 RATIONALE 

17317 None. 

17318 FUTURE DIRECTIONS 

17319 None. 

17320 SEE ALSO 

17321 ctime( ),ftime( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <sys/time.h> 

17322 CHANGE HISTORY 

17323 First released in Issue 4, Version 2. 

17324 Issue 5 

17325 Moved from X/OPEN UNIX extension to BASE. I 

17326 Issue 6 I 

17327 The DESCRIPTION is updated to refer to "seconds since the Epoch" rather than "seconds since I 

17328 00:00:00 UTC (Coordinated Universal Time), January 1 1980" for consistency with other time I 

17329 functions. I 
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17330 NAME 

17331 getuid — get a real user ID 

17332 SYNOPSIS 

17333 tinclude <unistd.h> 

17334 uid_t getuid (void) ; 

17335 DESCRIPTION 

17336 The getnid( ) function shall return the real user ID of the calling process. 

17337 RETURN VALUE 

17338 The getuid ( ) function is always successful and no return value is reserved to indicate the error. 

17339 ERRORS 

17340 No errors are defined. 

17341 EXAMPLES 

17342 Setting the Effective User ID to the Real User ID 

17343 The following example sets the effective user ID and the real user ID of the current process to the 

17344 real user ID of the caller. 

17345 #include <unistd.h> 

17346 tinclude <sys/types .h> 

17347 

17348 setreuid (getuidO, getuidO); 

17349 

17350 APPLICATION USAGE 

17351 None. 

17352 RATIONALE 

17353 None. 

17354 FUTURE DIRECTIONS 

17355 None. 

17356 SEE ALSO 

17357 geteidd{), getgid(), setuid(), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

17358 <sys/types.h>, <unistd.h> 

17359 CHANGE HISTORY 

17360 First released in Issue 1. 

17361 Derived from Issue 1 of the SVID. 

17362 Issue 4 

17363 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

17364 XSI-conformant systems. 

17365 The <unistd.h> header is added to the SYNOPSIS section. 

17366 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

17367 • The argument list is explicitly defined as void. 
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17368 

17369 

17370 

17371 

17372 

17373 

17374 


Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 
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17375 NAME 

17376 getutxent, getutxid, getutxline — get user accounting database entries 

17377 SYNOPSIS 

17378 xsi tinclude <utmpx.h> 

17379 

17380 

17381 

17382 

17383 DESCRIPTION 

17384 Refer to endiitxent (). 


struct utmpx *getutxent(void) ; 

struct utmpx *getutxid(const struct utmpx *id); 
struct utmpx *getutxline(const struct utmpx * line ); 
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17385 NAME 

17386 getwc — get a wide character from a stream 

17387 SYNOPSIS 

17388 tinclude <stdio.h> 

17389 tinclude <wchar.h> 

17390 wint_t getwc (FILE * stream) ; 

17391 DESCRIPTION 

17392 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

17393 conflict between the requirements described here and the ISO C standard is unintentional. This I 

17394 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

17395 The getzvc( ) function is equivalent to fgetwc ( ), except that if it is implemented as a macro it may 

17396 evaluate stream more than once, so the argument should never be an expression with side effects. 

17397 RETURN VALUE 

17398 Refer to fgetwc () . 

17399 ERRORS 

17400 Refer to fgetwc (). 

17401 EXAMPLES 

17402 None. 

17403 APPLICATION USAGE 

17404 Because it may be implemented as a macro, getzvc( ) may treat incorrectly a stream argument with 

17405 side effects. In particular, getzvc(*f++) does not necessarily work as expected. Therefore, use of 

17406 this function is not recommended ;fgetzvc( ) should be used instead. 

17407 RATIONALE 

17408 None. 

17409 FUTURE DIRECTIONS 

17410 None. 

17411 SEE ALSO 

17412 fgetzvc( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdio.h>, <wchar.h> 

17413 CHANGE HISTORY 

17414 First released as a World-wide Portability Interface in Issue 4. 

17415 Derived from the MSE working draft. 

17416 Issue 5 

17417 The Optional Header (OH) marking is removed from <stdio.h>. 
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17418 NAME 

17419 getwchar — get a wide character from a stdin stream 

17420 SYNOPSIS 

17421 #include <wchar.h> 

17422 wint_t getwchar (void) ; 

17423 DESCRIPTION 

17424 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

17425 conflict between the requirements described here and the ISO C standard is unintentional. This I 

17426 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

17427 The getwchar ( ) function is equivalent to getwc(stdin ). 

17428 RETURN VALUE 

17429 Refer to fgetwc{). 

17430 ERRORS 

17431 Refer to fgetwc( ). 

17432 EXAMPLES 

17433 None. 

17434 APPLICATION USAGE 

17435 If the wint_t value returned by getwchar () is stored into a variable of type wchar_t and then 

17436 compared against the wint_t macro WEOF, the comparison need never succeed. 

17437 RATIONALE 

17438 None. 

17439 FUTURE DIRECTIONS 

17440 None. 

17441 SEE ALSO 

17442 fgetwc(), getzvc( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

17443 CHANGE HISTORY 

17444 First released as a World-wide Portability Interface in Issue 4. 

17445 Derived from the MSE working draft. 
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17446 NAME 

17447 getwd — get the current working directory path name (LEGACY) 

17448 SYNOPSIS 

17449 xsi tinclude <unistd.h> 

17450 char *getwd(char *path_name) ; 

17451 

17452 DESCRIPTION 

17453 The getzvd( ) function determines an absolute path name of the current working directory of the 

17454 calling process, and copies that path name into the array pointed to by the path_name argument. 

17455 If the length of the path name of the current working directory is greater than ({PATH_MAX}+1) 

17456 including the null byte, getzvd ( ) shall fail and return a null pointer. 

17457 RETURN VALUE 

17458 Upon successful completion, a pointer to the string containing the absolute path name of the 

17459 current working directory shall be returned. Otherwise, getivd( ) shall return a null pointer and 

17460 the contents of the array pointed to by path_name are undefined. 

17461 ERRORS 

17462 No errors are defined. 

17463 EXAMPLES 

17464 None. 

17465 APPLICATION USAGE 

17466 For applications portability, the getczvd() function should be used to determine the current 

17467 working directory instead of getzvd (). 

17468 RATIONALE 

17469 None. 

17470 FUTURE DIRECTIONS 

17471 This function may be withdrawn in a future version. 

17472 SEE ALSO 

17473 getczvd( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

17474 CHANGE HISTORY 

17475 First released in Issue 4, Version 2. 

17476 Issue 5 

17477 Moved from X/OPEN UNIX extension to BASE. 

17478 Issue 6 

17479 This function is marked LEGACY. 
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17480 NAME 

17481 glob/ globfree — generate path names matching a pattern 


17482 Notes to Reviewers 

17483 This section with side shading will not appear in the final copy. - Ed. 

17484 This page will be reconciled with the .la version. 

17485 SYNOPSIS 

17486 tinclude <glob.h> 

17487 int glob (const char * pattern , int flags, 

17488 int (*errfunc) (const char *epath, int eerrno) , glob_t *pglob) ; 

17489 void globfree (glob_t *pglob) ; 

17490 DESCRIPTION 

17491 The glob() function is a path name generator that implements the rules defined in the 

17492 Commands and Utilities volume of IEEE Std. 1003.1-200x, Section 2.13, Pattern Matching 

17493 Notation, with optional support for rule 3 in the Commands and Utilities volume of 

17494 IEEE Std. 1003.1-200x, Section 2.13.3, Patterns Used for File Name Expansion. 


17495 

17496 

17497 

17498 

17499 

17500 


The structure type glob_t is defined in <glob.h> and includes at least the following members: 


Member Type 

Member Name 

Description 

size_t 
char ** 
size_t 

gl_pathc 

gljpathv 

gLoffs 

Count of paths matched by pattern. 

Pointer to a list of matched path names. 

Slots to reserve at the beginning of gl_pathv. 


17501 The argument pattern is a pointer to a path name pattern to be expanded. The glob() function 

17502 matches all accessible path names against this pattern and develops a list of all path names that 

17503 match. In order to have access to a path name, glob() requires search permission on every 

17504 component of a path except the last, and read permission on each directory of any file name 

17505 component of pattern that contains any of the following special characters: and ' ['. 

17506 The glob( ) function stores the number of matched path names into pglob-*gl_pathc and a pointer 

17507 to a list of pointers to path names into pglob-^gl_pathv . The path names are in sort order as 

17508 defined by the current setting of the LC_COLLATE category; see the System Interface Definitions I 

17509 volume of IEEE Std. 1003.1-200x, Section 7.3.2, LC_COLLATE . The first pointer after the last I 

17510 path name is a null pointer. If the pattern does not match any path names, the returned number I 

17511 of matched paths is set to 0, and the contents of pglob-^gl_pathv are implementation-dependent. 

17512 It is the caller's responsibility to create the structure pointed to by pglob. The glob() function 

17513 allocates other space as needed, including the memory pointed to by gl_pathv. The globfree () 

17514 function frees any space associated with pglob from a previous call to glob (). 

17515 Th e flags argument is used to control the behavior of glob(). The value of flags is a bitwise- 

17516 inclusive OR of zero or more of the following constants, which are defined in <glob.h>: 

17517 GLOB_APPEND Append path names generated to the ones from a previous call to glob (). 

17518 GLOB_DOOFFS Make use of pglob-^>gl_offs. If this flag is set, pglob-^>gl_ojfs is used to 

17519 specify how many null pointers to add to the beginning of 

17520 pglob—>gl_pathv . In other words, pglob-^gl_pathv shall point to 

17521 pglob-^gljojfs null pointers, followed by pglob-^gl_pathc path name 

17522 pointers, followed by a null pointer. 
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17523 

17524 

17525 

17526 

17527 

17528 

17529 

17530 

17531 

17532 

17533 

17534 

17535 

17536 

17537 

17538 

17539 

17540 

17541 

17542 

17543 

17544 

17545 

17546 

17547 

17548 

17549 

17550 

17551 

17552 

17553 

17554 

17555 

17556 

17557 

17558 

17559 

17560 

17561 

17562 

17563 


GLOB_ERR Causes glob() to return when it encounters a directory that it cannot open 

or read. Ordinarily, glob () continues to find matches. 

GLOB_MARK Each path name that is a directory that matches pattern has a slash 

appended. 

GLOB_NOCHECK Supports rule 3 in the Commands and Utilities volume of 
IEEE Std. 1003.1-200x, Section 2.13.3, Patterns Used for File Name 
Expansion. If pattern does not match any path name, then glob() shall 
return a list consisting of only pattern, and the number of matched path 
names is 1. 


GLOB_NOESCAPE Disable backslash escaping. 

GLOB_NOSORT Ordinarily, glob () sorts the matching path names according to the current 

setting of the LC_COLLATE category, see the System Interface Definitions I 
volume of IEEE Std. 1003.1-200x, Section 7.3.2, LC_COLLATE . When this I 
flag is used, the order of path names returned is unspecified. I 

The GLOB_APPEND flag can be used to append a new set of path names to those found in a 
previous call to glob(). The following rules apply to applications when two or more calls to I 
glob () are made with the same value of pglob and without intervening calls to globfree (): 

1. The first such call shall not set GLOB_APPEND. All subsequent calls shall set it. I 

2. All the calls shall set GLOB_DOOFFS, or all shall not set it. I 

3. After the second call, pglob-^gl_pathv points to a list containing the following: 

a. Zero or more null pointers, as specified by GLOB_DOOFFS and pglob^>gl_offs. 

b. Pointers to the path names that were in the pglob-*gl_pathv list before the call, in the 
same order as before. 


c. Pointers to the new path names generated by the second call, in the specified order. 

4. The count returned in pglob-^gl_pathc shall be the total number of path names from the 
two calls. 


5. The application can change any of the fields after a call to glob (). If it does, the application I 
shall reset them to the original value before a subsequent call, using the same pglob value, I 
to globfree () or glob () with the GLOB_APPEND flag. 

If, during the search, a directory is encountered that cannot be opened or read and errfnnc is not 
a null pointer, glob () calls ( *errfnnc ()) with two arguments: 

1. The epath argument is a pointer to the path that failed. 

2. The eerrno argument is the value of errno from the failure, as set by opendir (), readdir(), or 
stat(). (Other values may be used to report other errors not explicitly documented for 
those functions.) 


The following constants are defined as error return values for glob (): 

GLOB_ABORTED The scan was stopped because GLOB_ERR was set or ( *errfunc ()) 
returned non-zero. 


GLOB_NOMATCEl The pattern does not match any existing path name, and 
GLOB_NOCHECK was not set in flags. 

GLOB_NOSPACE An attempt to allocate memory failed. 
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17564 

17565 

17566 

17567 

17568 

17569 

17570 

17571 

17572 

17573 

17574 

17575 

17576 

17577 

17578 

17579 

17580 

17581 

17582 

17583 

17584 

17585 

17586 

17587 

17588 

17589 

17590 

17591 

17592 

17593 

17594 

17595 

17596 

17597 

17598 

17599 

17600 

17601 

17602 

17603 

17604 

17605 

17606 

17607 


If ( *errfunc ()) is called and returns non-zero, or if the GLOB_ERR flag is set in flags, glob() shall 
stop the scan and return GLOB_ABORTED after setting gl_pathc and gl_pathv in pglob to reflect 
the paths already scanned. If GLOB_ERR is not set and either errfitnc is a null pointer or 
( *errfunc ()) returns 0, the error shall be ignored. 

RETURN VALUE 

Upon successful completion, glob() shall return 0. The argument pglob—>gl_pathc shall return the I 
number of matched path names and the argument pglob-^gl_pathv shall contain a pointer to a 
null-terminated list of matched and sorted path names. However, if pglob-^gl_pathc is 0, the 
content of pglob-^gl_patlw is undefined. 

The globfree () function shall return no value. 

If glob() terminates due to an error, it shall return one of the non-zero constants defined in 
<glob.h>. The arguments pglob-i>gl_pathc and pglob—>gl_pathv are still set as defined above. 

ERRORS 

No errors are defined. 

EXAMPLES 

One use of the GLOB_DOOFFS flag is by applications that build an argument list for use with 
execv (), execve (), or execvp (). Suppose, for example, that an application wants to do the 
equivalent of: 

Is -1 *.c 

but for some reason: 

system("ls -1 *.c") 

is not acceptable. The application could obtain approximately the same result using the 
sequence: 

globbuf.gl_offs = 2; 

glob ("*.c", GLOB_DOOFF S, NULL, Sglobbuf); 
globbuf.gl_pathv[0] = "Is"; 
globbuf.gl_pathv[1] = "-1"; 
execvp ("Is", Sglobbuf.gl_pathv[0]) ; 

Using the same example: 

Is -1 *.c *.h 

could be approximately simulated using GLOB_APPEND as follows: 

globbuf.gl_offs = 2; 

glob GLOB_DOOFF S, NULL, Sglobbuf); 

glob ("*.h" , GLOB_DOOFFS|GLOB_APPEND, NULL, &globbuf); 

APPLICATION USAGE 

This function is not provided for the purpose of enabling utilities to perform path name 
expansion on their arguments, as this operation is performed by the shell, and utilities are 
explicitly not expected to redo this. Instead, it is provided for applications that need to do path 
name expansion on strings obtained from other sources, such as a pattern typed by a user or 
read from a file. 

If a utility needs to see if a path name matches a given pattern, it can us efnmatch (). 

Note that gl_pathc and gl_pathv have meaning even if glob () fails. This allows glob{) to report 
partial results in the event of an error. However, if gl_pathc is 0, gl_pathv is unspecified even if 

554 Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


glob() 


17608 

17609 

17610 

17611 

17612 

17613 

17614 

17615 

17616 

17617 

17618 

17619 

17620 

17621 

17622 

17623 

17624 

17625 

17626 

17627 

17628 

17629 

17630 

17631 

17632 

17633 

17634 

17635 

17636 

17637 

17638 

17639 

17640 

17641 

17642 

17643 

17644 


g!ob() did not return an error. 

The GLOB_NOCHECK option could be used when an application wants to expand a path name 
if wildcards are specified, but wants to treat the pattern as just a string otherwise. The sh utility 
might use this for option-arguments, for example. 

The new path names generated by a subsequent call with GLOB_APPEND are not sorted 
together with the previous path names. This mirrors the way that the shell handles path name 
expansion when multiple expansions are done on a command line. 

Applications that need tilde and parameter expansion should use ivordexp(). 

RATIONALE 

It was claimed that the GLOB_DOOFFS flag is unnecessary because it could be simulated using: 

new = (char **)malloc((n + pglob—»gl_pathc + 1) 

* sizeof (char *)); 

(void) memcpy (new+n, pglob—»gl_pathv, 

pglob—>gl_pathc * sizeof (char *)); 

(void) memset (new, 0, n * sizeof (char *)); 
free (pglob—>gl_pathv); 
pglob—»gl_pathv = new; 

However, this assumes that the memory pointed to by gljpathv is a block that was separately 
created using malloc(). This is not necessarily the case. An application should make no 
assumptions about how the memory referenced by fields in pglob was allocated. It might have 
been obtained from malloc () in a large chunk and then carved up within glob(), or it might have 
been created using a different memory allocator. It is not the intent of the standard developers to 
specify or imply how the memory used by glob ( ) is managed. 

The GLOB_APPEND flag would be used when an application wants to expand several different 
patterns into a single list. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

exec,fnmatch(), opendir( ), readdir( ), stat( ), zvordexp( ), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <glob.h>, the Commands and Utilities volume of IEEE Std. 1003.1-200x 

CHANGE HISTORY 

First released in Issue 4. 

Derived from the ISO POSIX-2 standard. 


Issue 5 

Moved from POSIX2 C-language Binding to BASE. 

Issue 6 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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17645 NAME 

17646 gmtime, gmtime_r — convert a time value to a broken-down UTC time 

17647 SYNOPSIS 

17648 tinclude <time.h> 

17649 struct tm *gmtime(const time_t *timer); 

17650 TSF struct tm *gmtime_r (const time_t * clock, struct tm * result); 

17651 

17652 DESCRIPTION 

17653 cx For gmtime (): The functionality described on this reference page is aligned with the ISOC 

17654 standard. Any conflict between the requirements described here and the ISO C standard is I 

17655 unintentional. This volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

17656 The gmtime ( ) function shall convert the time in seconds since the Epoch pointed to by timer into 

17657 a broken-down time, expressed as Coordinated Universal Time (UTC). 

17658 cx The gmtime ( ) funtion need not be reentrant. A function that is not required to be reentrant is not 

17659 required to be thread-safe. 

17660 tsf The gmtime_r{ ) function shall convert the calendar time pointed to by clock into a broken-down 

17661 time expressed as Coordinated Universal Time (UTC). The broken-down time is stored in the 

17662 structure referred to by result. The gmtime_r{ ) function shall also return the address of the same 

17663 structure. 

17664 RETURN VALUE 

17665 The gmtime( ) function shall return a pointer to a struct tm. 

17666 tsf Upon successful completion, gmtime_r{) shall return the address of the structure pointed to by 

17667 the argument result. If an error is detected, or UTC is not available, gmtime_r{ ) shall return a null 

17668 pointer. 

17669 ERRORS 

17670 No errors are defined. 

17671 EXAMPLES 

17672 None. 

17673 APPLICATION USAGE 

17674 The asctime(), ctime(), gmtime(), and localtime () functions return values in one of two static 

17675 objects: a broken-down time structure and an array of char. Execution of any of the functions 

17676 may overwrite the information returned in either of these objects by any of the other functions. 

17677 The gmtime_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 

17678 of possibly using a static data area that may be overwritten by each call. 

17679 RATIONALE 

17680 None. 

17681 FUTURE DIRECTIONS 

17682 None. 

17683 SEE ALSO 

17684 asctime(), clock(), ctime( ), difftime(), localtime(), mktime( ), strftime(), strptime(), time(), utime( ), 

17685 the System Interface Definitions volume of IEEE Std. 1003.1-200x, <time.h> 
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17686 

17687 

17688 

17689 

17690 

17691 

17692 

17693 

17694 

17695 

17696 

17697 

17698 

17699 

17700 

17701 

17702 


CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

In the APPLICATION USAGE section, the list of functions with which this function may interact 
is revised and the wording clarified. 

The following change is incorporated for alignment with the ISO C standard: 

• The type of argument timer is changed from time_t* to const time_t*- 

Issue 5 

A note indicating that the gmtime () function need not be reentrant is added to the 
DESCRIPTION. 

The gmtime_r {) function is included for alignment with the POSIX Threads Extension. 

Issue 6 

The gmtime_r () function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS option. 
Extensions beyond the ISO C standard are now marked. 

The APPLICATION USAGE section is updated to include a note on the thread-safe function and 
its avoidance of possibly using a static data area. 
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17703 

17704 

17705 

17706 

17707 

17708 

17709 

17710 

17711 

17712 

17713 

17714 

17715 

17716 

17717 

17718 

17719 

17720 

17721 

17722 

17723 

17724 

17725 

17726 

17727 

17728 

17729 

17730 

17731 

17732 

17733 

17734 

17735 

17736 

17737 

17738 

17739 

17740 

17741 

17742 


NAME 

grantpt — grant access to the slave pseudo-terminal device 

SYNOPSIS 

xsi tinclude <stdlib.h> 

int grantpt(int fildes) ; 

DESCRIPTION 

The grantpt () function shall change the mode and ownership of the slave pseudo-terminal 
device associated with its master pseudo-terminal counterpart. The fildes argument is a file 
descriptor that refers to a master pseudo-terminal device. The user ID of the slave shall be set to 
the real UID of the calling process and the group ID shall be set to an unspecified group ID. The 
permission mode of the slave pseudo-terminal shall be set to readable and writable by the 
owner, and writable by the group. 

The behavior of the grantpt () function is unspecified if the application has installed a signal 
handler to catch SIGCHLD signals. 

RETURN VALUE 

Upon successful completion, grantpt () shall return 0; otherwise, it shall return -1 and set errno to 
indicate the error. 

ERRORS 

The grantpt () 

[EBADF] 

[EINVAL] 

[EACCES] 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

open(), ptsname(), nnlockpt(), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

<stdlib.h> 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 

The last paragraph of the DESCRIPTION is moved from the APPLICATION USAGE section in 
previous issues. 


function may fail if: 

Th e fildes argument is not a valid open file descriptor. 

Th e fildes argument is not associated with a master pseudo-terminal device. 
The corresponding slave pseudo-terminal device could not be accessed. 
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17743 

17744 

17745 

17746 

17747 

17748 

17749 

17750 

17751 

17752 

17753 

17754 

17755 

17756 

17757 

17758 

17759 

17760 

17761 

17762 

17763 

17764 

17765 

17766 

17767 

17768 

17769 


NAME 

h_errno — error return value for network database operations (LEGACY) 

SYNOPSIS 

#include <netdb.h> 

DESCRIPTION 

Note that this method of returning errors is used only in connection with legacy functions. 

The <netdb.h> header provides a declaration of h_errno as a modifiable l -value of type int. 

It is unspecified whether h_errno is a macro or an identifier declared with external linkage. If a 
macro definition is suppressed in order to access an actual object, or a program defines an 
identifier with the name h_errno, the behavior is undefined. 

RETURN VALUE 

None. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

Applications should obtain the definition of h_errno by the inclusion of the <netdb.h> header. 
The practice of defining h_errno in a program as an extern int h_errno is obsolescent. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

h_errno may be withdrawn in a future version. 

SEE ALSO 

endhostent(), errno, the System Interface Definitions volume of IEEE Std. 1003.1-200x, <netdb.h> 
CHANGE HISTORY 

First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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17770 NAME 

17771 hcreate, hdestroy, hsearch — manage hash search table 

17772 SYNOPSIS 

17773 xsi tinclude <search.h> 

17774 

17775 

17776 

17777 

17778 DESCRIPTION 

17779 The hcreate( ), hdestroy (), and hsearch () functions manage hash search tables. 

17780 The hcreate( ) function allocates sufficient space for the table, and the application shall ensure it is I 

17781 called before hsearch () is used. The net argument is an estimate of the maximum number of I 

17782 entries that the table shall contain. This number may be adjusted upward by the algorithm in 

17783 order to obtain certain mathematically favorable circumstances. 

17784 The hdestroy () function disposes of the search table, and may be followed by another call to 

17785 hcreate( ). After the call to hdestroy (), the data can no longer be considered accessible. 

17786 The hsearch () function is a hash-table search routine. It shall return a pointer into a hash table 

17787 indicating the location at which an entry can be found. The item argument is a structure of type 

17788 ENTRY (defined in the <search.h> header) containing two pointers: item.key points to the 

17789 comparison key (a char*), and item.data (a void*) points to any other data to be associated with 

17790 that key. The comparison function used by hsearch () is strcmp(). The action argument is a 

17791 member of an enumeration type ACTION indicating the disposition of the entry if it cannot be 

17792 found in the table. ENTER indicates that the item should be inserted in the table at an 

17793 appropriate point. FIND indicates that no entry should be made. Unsuccessful resolution is 

17794 indicated by the return of a null pointer. 

17795 These functions need not be reentrant. A function that is not required to be reentrant is not 

17796 required to be thread-safe. 

17797 RETURN VALUE 

17798 The hcreate( ) function shall return 0 if it cannot allocate sufficient space for the table; otherwise, 

17799 it shall return non-zero. 

17800 The hdestroy () function shall return no value. 

17801 The hsearch () function shall return a null pointer if either the action is FIND and the item could 

17802 not be found or the action is ENTER and the table is full. 

17803 ERRORS 

17804 The hcreate( ) and hsearch () functions may fail if: 

17805 [ENOMEM] Insufficient storage space is available. 


17806 EXAMPLES 


17807 

17808 

17809 

The following example reads in strings followed by two numbers and stores them in a hash 
table, discarding duplicates. It then reads in strings and finds the matching entry in the hash 
table and prints it out. 

17810 

#include <stdio.h> 


17811 

#include <search.h> 


17812 

#include <string.h> 


17813 

struct info { 

/* This is the info stored in the table */ 

17814 

int age, room; 

/* other than the key. */ 


int hcreate(size_t nel) ; 
void hdestroy(void) ; 

ENTRY *hsearch (ENTRY item, ACTION action ); 
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17815 } ; 

17816 tdefine NUM_EMPL 5000 /* # of elements in search table. */ 


17817 

17818 

17819 

17820 

17821 

17822 

17823 

17824 

17825 

17826 


int main(void) 

{ 

char string_space[NUM_EMPL*20]; /* Space to store strings. */ 

struct info info_space[NUM_EMPL]; /* Space to store employee info. * 
char *str_ptr = string_space; /* Next space in string_space. */ 

struct info *info_ptr = info_space; 

/* Next space in info_space. */ 

ENTRY item; 

ENTRY *found_item; /* Name to look for in table. */ 
char name_to_find[30]; 


17827 


int i = 0; 


17828 

17829 

17830 

17831 


/* Create table; no error checking is performed. */ 
(void) hcreate(NUM_EMPL); 

while (scanf("%s%d%d", str_ptr, &info_ptr—>age, 

&info_ptr—>room) != EOF && i++ < NUM_EMPL) { 


17832 

17833 

17834 

17835 

17836 


/* Put information in structure, and structure in item. */ 

item.key = str_ptr; 

item.data = info_ptr; 

str_ptr += strlen(str_ptr) + 1; 

info_ptr++; 


17837 

17838 

17839 


/* Put item into table. */ 
(void) hsearch(item, ENTER); 


17840 

17841 

17842 

17843 


/* Access table. */ 

item.key = name_to_find; 

while (scanf("%s", item.key) != EOF) { 

if ((found_item = hsearch(item, FIND)) != NULL) { 


17844 

17845 

17846 

17847 

17848 

17849 

17850 

17851 

17852 

17853 


/* If item is in the table. */ 

(void)printf("found %s, age = %d, room = %d\n", 
found_item—>key, 

((struct info *)found_item—>data)—>age, 

((struct info *)found_item—>data)—>room) ; 

} else 

(void)printf("no such employee %s\n", name_to_find); 

} 

return 0; 


17854 APPLICATION USAGE 

17855 The hcreate () and hsearch () functions may use malloc () to allocate space. 

17856 RATIONALE 

17857 None. 
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17858 FUTURE DIRECTIONS 

17859 None. 

17860 SEE ALSO 

17861 bsearch(), lsearch(), malloc(), strcmp(), tsearch(), the System Interface Definitions volume of 

17862 IEEE Std. 1003.1-200x, <search.h> 

17863 CHANGE HISTORY 

17864 First released in Issue 1. 

17865 Derived from Issue 1 of the SVID. 

17866 Issue 4 

17867 In the SYNOPSIS section, the type of argument net in the declaration of hcreate( ) is changed from 

17868 unsigned to size_t, and the argument list is explicitly defined as void in the declaration of 

17869 hdestroy{). 

17870 In the DESCRIPTION, the type of the comparison key is explicitly defined as char*, the type of 

17871 item.data is explicitly defined as void*, and a statement is added indicating that hsearch() uses 

17872 strcmp( ) as the comparison function. 

17873 In the EXAMPLES section, the sample code is updated to use ISO C standard syntax. 

17874 An ERRORS section is added and [ENOMEM] is defined as an error that may be returned by 

17875 hsearch () and hcreate( ). 

17876 Issue 6 

17877 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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17878 NAME 

17879 htonl, htons, ntohl, ntohs — convert values between host and network byte order 

17880 SYNOPSIS 

17881 tinclude <arpa/inet. h> 

17882 uint32_t htonl (uint32_t hostlong) ; 

17883 uintl6_t htons (uintl6_t hostshort) } 

17884 uint32_t ntohl (uint32_t netlong) ; 

17885 uintl6_t ntohs (uintl6_t net short) ; 

17886 DESCRIPTION 

17887 These functions shall convert 16-bit and 32-bit quantities between network byte order and host 

17888 byte order. 

17889 On some implementations, these functions are defined as macros that expand to the value of 

17890 their argument. 

17891 The uint32_t and uintl6_t types are made available by inclusion of the <inttypes.h> header. 

17892 RETURN VALUE 

17893 The htonl () and htons () functions shall return the argument value converted from host to 

17894 network byte order. 

17895 The ntohl() and ntohs () functions shall return the argument value converted from network to 

17896 host byte order. 

17897 ERRORS 

17898 No errors are defined. 

17899 EXAMPLES 

17900 None. 

17901 APPLICATION USAGE 

17902 These functions are most often used in conjunction with IPv4 addresses and ports as returned by 

17903 gethostent( ) and get ser vent (). 

17904 RATIONALE 

17905 None. 

17906 FUTURE DIRECTIONS 

17907 None. 

17908 SEE ALSO 

17909 endhostent(), endservent(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

17910 <inttypes.h>, <arpa/inet.h> 

17911 CHANGE HISTORY 

17912 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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17913 NAME 

17914 htons — convert values between host and network byte order 

17915 SYNOPSIS 

17916 tinclude <arpa/inet. h> 

17917 uintl6_t htons (uintl6_t hostshort) } 

17918 DESCRIPTION 

17919 Refer to htonl (). 
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17920 NAME 

17921 hypot — Euclidean distance function 

17922 SYNOPSIS 

17923 xsi tinclude <math.h> 

17924 double hypot (double x, double y) ; 

17925 

17926 DESCRIPTION 

17927 The hypot () function shall compute the value of the square root of x 2 +y 2 . 

17928 An application wishing to check for error situations should set errno to 0 before calling hypot (). 

17929 If errno is non-zero on return, or the return value is HUGE_VAL or NaN, an error has occurred. 

17930 RETURN VALUE 

17931 Upon successful completion, hypot () shall return the length of the hypotenuse of a right-angled 

17932 triangle with sides of length x and y. 

17933 If the result would cause overflow, HUGE_VAL shall be returned and errno may be set to 

17934 [ERANGE]. 

17935 If x or y is NaN, NaN shall be returned, and errno may be set to [EDOM]. 

17936 If the correct result would cause underflow, 0 shall be returned and errno may be set to 

17937 [ERANGE]. 

17938 ERRORS 

17939 The hypot () function may fail if: 

17940 [EDOM] The value of x or y is NaN. 

17941 [ERANGE] The result overflows or underflows. 

17942 No other errors shall occur. 

17943 EXAMPLES 

17944 None. 

17945 APPLICATION USAGE 

17946 The hypot () function takes precautions against overflow during intermediate steps of the 

17947 computation. If the calculated result would still overflow a double, then hypot () shall return 

17948 HUGE_VAL. 

17949 RATIONALE 

17950 None. 

17951 FUTURE DIRECTIONS 

17952 None. 

17953 SEE ALSO 

17954 isnan (), sqrt( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

17955 CHANGE HISTORY 

17956 First released in Issue 1. 

17957 Derived from Issue 1 of the SVID. 

17958 Issue 4 

17959 References to matherr{ ) are removed. 

17960 The RETURN VALUE and ERRORS sections are substantially rewritten to rationalize error 

17961 handling in the mathematics functions. 
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17962 

17963 

17964 


Issue 5 

The DESCRIPTION is updated to indicate how an application should check for an error. This 
text was previously published in the APPLICATION USAGE section. 
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17965 NAME 

17966 iconv — codeset conversion function 

17967 SYNOPSIS 

17968 xsi tinclude <iconv.h> 

17969 

17970 

17971 

17972 DESCRIPTION 

17973 The iconv () function shall convert the sequence of characters from one codeset, in the array 

17974 specified by inbuf, into a sequence of corresponding characters in another codeset, in the array 

17975 specified by outbuf. The codesets are those specified in the iconv_open () call that returned the 

17976 conversion descriptor, cd. The inbuf argument points to a variable that points to the first 

17977 character in the input buffer and inbytesleft indicates the number of bytes to the end of the buffer 

17978 to be converted. The outbuf argument points to a variable that points to the first available byte in 

17979 the output buffer and outbytesleft indicates the number of the available bytes to the end of the 

17980 buffer. 

17981 For state-dependent encodings, the conversion descriptor cd is placed into its initial shift state by 

17982 a call for which inbuf is a null pointer, or for which inbuf points to a null pointer. When iconv( ) is 

17983 called in this way, and if outbuf is not a null pointer or a pointer to a null pointer, and outbytesleft 

17984 points to a positive value, iconv () shall place, into the output buffer, the byte sequence to change 

17985 the output buffer to its initial shift state. If the output buffer is not large enough to hold the 

17986 entire reset sequence, iconv() shall fail and set errno to [E2BIG]. Subsequent calls with inbuf as 

17987 other than a null pointer or a pointer to a null pointer cause the conversion to take place from 

17988 the current state of the conversion descriptor. 

17989 If a sequence of input bytes does not form a valid character in the specified codeset, conversion 

17990 stops after the previous successfully converted character. If the input buffer ends with an 

17991 incomplete character or shift sequence, conversion stops after the previous successfully 

17992 converted bytes. If the output buffer is not large enough to hold the entire converted input, 

17993 conversion stops just prior to the input bytes that would cause the output buffer to overflow. 

17994 The variable pointed to by inbuf is updated to point to the byte following the last byte 

17995 successfully used in the conversion. The value pointed to by inbytesleft is decremented to reflect 

17996 the number of bytes still not converted in the input buffer. The variable pointed to by outbuf is 

17997 updated to point to the byte following the last byte of converted output data. The value pointed 

17998 to by outbytesleft is decremented to reflect the number of bytes still available in the output buffer. 

17999 For state-dependent encodings, the conversion descriptor is updated to reflect the shift state in 

18000 effect at the end of the last successfully converted byte sequence. 

18001 If iconv () encounters a character in the input buffer that is valid, but for which an identical 

18002 character does not exist in the target codeset, iconv () performs an implementation-dependent 

18003 conversion on this character. 

18004 RETURN VALUE 

18005 The iconv () function shall update the variables pointed to by the arguments to reflect the extent 

18006 of the conversion and return the number of non-identical conversions performed. If the entire 

18007 string in the input buffer is converted, the value pointed to by inbytesleft shall be 0. If the input 

18008 conversion is stopped due to any conditions mentioned above, the value pointed to by inbytesleft 

18009 shall be non-zero and errno shall be set to indicate the condition. If an error occurs iconv () shall 

18010 return (size_t)-l and set errno to indicate the error. 


size_t iconv(iconv_t cd, char ** inbuf, size_t * inbytesleft, 
char ** outbuf, size_t * outbytesleft) ; 
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18011 

18012 

18013 

18014 

18015 

18016 

18017 

18018 

18019 

18020 
18021 

18022 

18023 

18024 

18025 

18026 

18027 

18028 

18029 

18030 

18031 

18032 

18033 

18034 

18035 

18036 

18037 

18038 

18039 

18040 

18041 

18042 

18043 

18044 

18045 

18046 

18047 

18048 

18049 

18050 

18051 

18052 

18053 


ERRORS 

The iconv() function shall fail if: 

[EILSEQ] Input conversion stopped due to an input byte that does not belong to the 

input codeset. 

[E2BIG] Input conversion stopped due to lack of space in the output buffer. 

[EINVAL] Input conversion stopped due to an incomplete character or shift sequence at 

the end of the input buffer. 

The iconv() function may fail if: 

[EBADF] The cd argument is not a valid open conversion descriptor. 

EXAMPLES 

None. 

APPLICATION USAGE 

The inbuf argument indirectly points to the memory area which contains the conversion input 
data. The oiitbuf argument indirectly points to the memory area which is to contain the result of 
the conversion. The objects indirectly pointed to by inbuf and outbuf are not restricted to 
containing data that is directly representable in the ISO C standard language char data type. The 
type of inbuf and outbuf, char* 51 ', does not imply that the objects pointed to are interpreted as 
null-terminated C strings or arrays of characters. Any interpretation of a byte sequence that 
represents a character in a given character set encoding scheme is done internally within the 
codeset converters. For example, the area pointed to indirectly by inbuf and/or outbuf can 
contain all zero octets that are not interpreted as string terminators but as coded character data 
according to the respective codeset encoding scheme. The type of the data (char, short int, long 
int, and so on) read or stored in the objects is not specified, but may be inferred for both the 
input and output data by the converters determined by the fromcode and tocode arguments of 
iconv_open (). 

Regardless of the data type inferred by the converter, the size of the remaining space in both 
input and output objects (the intbytesleft and outbytesleft arguments) is always measured mbytes. 

For implementations that support the conversion of state-dependent encodings, the conversion 
descriptor must be able to accurately reflect the shift-state in effect at the end of the last 
successful conversion. It is not required that the conversion descriptor itself be updated, which 
would require it to be a pointer type. Thus, implementations are free to implement the 
descriptor as a handle (other than a pointer type) by which the conversion information can be 
accessed and updated. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

iconv_open(), iconv_close( ), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

<iconv.h> 

CHANGE HISTORY 

First released in Issue 4. 

Derived from the HP-UX Manual. 
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18054 Issue 6 

18055 The SYNOPSIS has been corrected to align with the <iconv.h> reference page. 
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18056 NAME 

18057 iconv_close — codeset conversion deallocation function 

18058 SYNOPSIS 

18059 xsi tinclude <iconv.h> 

18060 int iconv_close (iconv_t cd) ; 

18061 

18062 DESCRIPTION 

18063 The iconi’_close() function deallocates the conversion descriptor cd and all other associated 

18064 resources allocated by iconv_open (). 

18065 If a file descriptor is used to implement the type iconv_t, that file descriptor is closed. 

18066 RETURN VALUE 

18067 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 

18068 indicate the error. 

18069 ERRORS 

18070 The iconv_close() function may fail if: 

18071 [EBADF] The conversion descriptor is invalid. 

18072 EXAMPLES 

18073 None. 

18074 APPLICATION USAGE 

18075 None. 

18076 RATIONALE 

18077 None. 

18078 FUTURE DIRECTIONS 

18079 None. 

18080 SEE ALSO 

18081 iconv (), iconv_open(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

18082 <iconv.h> 

18083 CHANGE HISTORY 

18084 First released in Issue 4. 

18085 Derived from the HP-UX Manual. 
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18086 NAME 

18087 iconv_open — codeset conversion allocation function 

18088 SYNOPSIS 

18089 xsi tinclude <iconv.h> 

18090 iconv_t iconv_open (const char *tocode, const char *fromcode ); 

18091 

18092 DESCRIPTION 

18093 The iconv_open () function shall return a conversion descriptor that describes a conversion from 

18094 the codeset specified by the string pointed to by the fromcode argument to the codeset specified 

18095 by the string pointed to by the tocode argument. For state-dependent encodings, the conversion 

18096 descriptor is in a codeset-dependent initial shift state, ready for immediate use with iconv (). 

18097 Settings of fromcode and tocode and their permitted combinations are implementation-dependent. 

18098 A conversion descriptor remains valid in a process until that process closes it. 

18099 If a file descriptor is used to implement conversion descriptors, the FD_CLOEXEC flag shall be 

18100 set; see <fcntl.h>. 

18101 RETURN VALUE 

18102 Upon successful completion, iconv_open() shall return a conversion descriptor for use on 

18103 subsequent calls to iconv (). Otherwise, iconv_open() shall return (iconv_t)-l and set errno to 

18104 indicate the error. 

18105 ERRORS 

18106 The iconv_open () 

18107 [EMFILE] 

18108 [ENFILE] 

18109 [ENOMEM] 

18110 [EINVAL] 

18111 

18112 EXAMPLES 

18113 None. 

18114 APPLICATION USAGE 

18115 Some implementations of iconv_open() use malloc() to allocate space for internal buffer areas. 

18116 The iconv_open () function may fail if there is insufficient storage space to accommodate these 

18117 buffers. 

18118 Portable applications must assume that conversion descriptors are not valid after a call to one of 

18119 the exec functions. 

18120 RATIONALE 

18121 None. 

18122 FUTURE DIRECTIONS 

18123 None. 

18124 SEE ALSO 

18125 iconv (), iconv_close(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

18126 <iconv.h> 


function may fail if: 

{OPEN_MAX} file descriptors are currently open in the calling process. 

Too many files are currently open in the system. 

Insufficient storage space is available. 

The conversion specified by fromcode and tocode is not supported by the 
implementation. 
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18127 CHANGE HISTORY 

18128 First released in Issue 4. 

18129 Derived from the HP-UX Manual. 
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18130 NAME 

18131 if_freenameindex — free memory allocated by ifnameindex () 

18132 SYNOPSIS 

18133 tinclude <net/if.h> 

18134 void if_freenameindex (struct if_nameindex *ptr) ; 

18135 DESCRIPTION 

18136 The if_freenameindex() function shall free the memory allocated by if_nameindex(). The 

18137 if_nameindex argument shall be a pointer that was returned by if_nameindex(). After 

18138 if_freenameindex() has been called, the application should not use the array of which ptr is the 

18139 address. 

18140 RETURN VALUE 

18141 None. 

18142 ERRORS 

18143 The if_freenameindex ( ) function may fail if: 

18144 [EFAULT] The if_nameindex argument is not a pointer that was returned by 

18145 if_nameindex(). Note that implementations need not always detect this fault. 

18146 If an implementation does not do so, the results are unspecified. 

18147 EXAMPLES 

18148 None. 

18149 APPLICATION USAGE 

18150 None. 

18151 RATIONALE 

18152 None. 

18153 FUTURE DIRECTIONS 

18154 None. 

18155 SEE ALSO 

18156 getsockopt(), if_indextoname (), if_nameindex(), if_nametoindex( ), setsockopt( ), the System Interface 

18157 Definitions volume of IEEE Std. 1003.1-200x, <net/if.h> 

18158 CHANGE HISTORY 

18159 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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18160 NAME 

18161 if_indextoname — map a function index to its corresponding name 

18162 SYNOPSIS 

18163 tinclude <net/if.h> 

18164 char *if_indextoname (unsigned int if index, char * if name) ; 

18165 DESCRIPTION 

18166 The if_indextoname( ) function shall map a function index to its corresponding name. 

18167 When this function is called, ifname shall point to a buffer of at least jIFNAMSIZ} bytes. The 

18168 function shall place in this buffer the name of the function with index ifindex. 

18169 RETURN VALUE 

18170 If ifindex is a function index, then the function shall return the value supplied in ifname, which 

18171 points to a buffer now containing the function name. Otherwise, the function shall return a 

18172 NULL pointer. 

18173 ERRORS 

18174 The if_indextoname( ) function shall fail if: 

18175 [EFAULT] The buffer pointed to by ifname cannot be accessed or written. 

18176 EXAMPLES 

18177 None. 

18178 APPLICATION USAGE 

18179 None. 

18180 RATIONALE 

18181 None. 

18182 FUTURE DIRECTIONS 

18183 None. 

18184 SEE ALSO 

18185 getsockopt(), if_freenameindex(), if_nameindex (), if_nametoindex( ), setsockopt(), the System 

18186 Interface Definitions volume of IEEE Std. 1003.1-200x, <net/if.h> 

18187 CHANGE HISTORY 

18188 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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18189 NAME 

18190 if_nameindex — return all function names and indexes 

18191 SYNOPSIS 

18192 #include <net/if.h> 

18193 struct if_nameindex * if_name index (void) ; 

18194 DESCRIPTION 

18195 The if_nameindex() function shall return an array of if_nameindex structures, one structure per 

18196 function. The end of the array is indicated by a structure with an if_index field of zero and an 

18197 if_name field of NULL. 

18198 Applications should call if_freenameindex() to release the memory that may be dynamically 

18199 allocated by this function, after they have finished using it. 

18200 RETURN VALUE 

18201 Array of structures identifying local functions. A NULL pointer is returned upon an error, with 

18202 errno set to indicate the nature of the error. 

18203 ERRORS 

18204 The if_nameindex( ) function may fail if: 

18205 [ENOBUFS] Insufficient resources are available to complete the function. 

18206 EXAMPLES 

18207 None. 

18208 APPLICATION USAGE 

18209 None. 

18210 RATIONALE 

18211 None. 

18212 FUTURE DIRECTIONS 

18213 None. 

18214 SEE ALSO 

18215 getsockopt(), if_freenameindex(), if_indextoname(), if_nametoindex(), setsockopt(), the System 

18216 Interface Definitions volume of IEEE Std. 1003.1-200x, <net/if.h> 

18217 CHANGE HISTORY 

18218 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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18219 NAME 

18220 if_nametoindex — map a function name to its corresponding index 

18221 SYNOPSIS 

18222 #include <net/if.h> 

18223 unsigned int if_nametoindex (const char * ifname) ; 

18224 DESCRIPTION 

18225 The if_nametoindex( ) function shall return the function index corresponding to name ifname. 

18226 RETURN VALUE 

18227 The corresponding index if ifname is the name of a function; otherwise, zero. 

18228 ERRORS 

18229 The if_nametoindex( ) function shall fail if: 

18230 [EFAULT] The buffer pointed to by ifname cannot be accessed. 

18231 EXAMPLES 

18232 None. 

18233 APPLICATION USAGE 

18234 None. 

18235 RATIONALE 

18236 None. 

18237 FUTURE DIRECTIONS 

18238 None. 

18239 SEE ALSO 

18240 getsockopt(), if_freenameindex(), if_indextoname(), if_nameindex(), setsockopt(), the System 

18241 Interface Definitions volume of IEEE Std. 1003.1-200x, <net/if.h> 

18242 CHANGE HISTORY 

18243 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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18244 NAME 

18245 ilogb — return an unbiased exponent 

18246 SYNOPSIS 

18247 xsi tinclude <math.h> 

18248 int ilogb (double x) 

18249 

18250 DESCRIPTION 

18251 The ilogb () function shall return the exponent part of x. Formally, the return value is the integral 

18252 part of log,. I x I as a signed integral value, for non-zero x, where r is the radix of the machine's 

18253 floating point arithmetic. 

18254 The call ilogb(x) is equivalent to (int )logb(x). 

18255 RETURN VALUE 

18256 Upon successful completion, ilogb () shall return the exponent part of x. 

18257 If x is 0, then ilogb () shall return -{INT_MIN}. If x is NaN or ±Inf, then ilogb () shall return 

18258 |INT_MAX}. 

18259 ERRORS 

18260 No errors are defined. 

18261 EXAMPLES 

18262 None. 

18263 APPLICATION USAGE 

18264 None. 

18265 RATIONALE 

18266 None. 

18267 FUTURE DIRECTIONS 

18268 None. 

18269 SEE ALSO 

18270 logb( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

18271 CHANGE HISTORY 

18272 First released in Issue 4, Version 2. 

18273 Issue 5 

18274 Moved from X/OPEN UNIX extension to BASE. 
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18275 NAME 

18276 index — character string operations (LEGACY) 

18277 SYNOPSIS 

18278 xsi tinclude <strings.h> 

18279 char *index(const char *s, int c) ; 

18280 

18281 DESCRIPTION 

18282 The index( ) function is identical to strchr (). 

18283 RETURN VALUE 

18284 See strchr(). 

18285 ERRORS 

18286 See strchr (). 

18287 EXAMPLES 

18288 None. 

18289 APPLICATION USAGE 

18290 strchr( ) is preferred over this function. 

18291 For maximum portability, it is recommended to replace the function call to index( ) as follows: 

18292 tdefine index (a, b) strchr ( (a) , (b) ) 

18293 RATIONALE 

18294 None. 

18295 FUTURE DIRECTIONS 

18296 This function may be withdrawn in a future version. 

18297 SEE ALSO 

18298 strclir( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <strings.h> 

18299 CHANGE HISTORY 

18300 First released in Issue 4, Version 2. 

18301 Issue 5 

18302 Moved from X/OPEN UNIX extension to BASE. 

18303 Issue 6 

18304 This function is marked LEGACY. 
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18305 NAME 

18306 inet_addr, inetjnaof (LEGACY), inet_makeaddr (LEGACY), inet_netof (LEGACY), 

18307 inet_network (LEGACY), inet_ntoa — IPv4 address manipulation 

18308 SYNOPSIS 

18309 tinclude <arpa/inet. h> 

18310 in_addr_t inet_addr (const char * cp) ; 

18311 in_addr_t inet_lnaof (struct in_addr in); 

18312 struct in_addr inet_makeaddr (in_addr_t net, in_addr_t lna) ; 

18313 in_addr_t inet_netof (struct in_addr in); 

18314 in_addr_t inet_network (const char * cp) ; 

18315 char *inet_ntoa (struct in_addr in); 


18316 DESCRIPTION 

18317 The inet_nddr() function shall convert the string pointed to by cp, in the standard IPv4 dotted 

18318 decimal notation, to an integer value suitable for use as an Internet address. 

18319 The inetjnaof ( ) function shall take an Internet host address specified by in and extract the local 

18320 network address part, in host byte order. 

18321 The inet_makeaddr( ) function shall take the Internet network number specified by net and the 

18322 local network address specified by lna, both in host byte order, and construct an Internet address 

18323 from them. 

18324 The inet_netof() function shall take an Internet host address specified by in and extract the 

18325 network number part, in host byte order. 

18326 The inet_netivork( ) function shall convert the string pointed to by cp, in the standard IPv4 dotted 

18327 decimal notation, to an integer value suitable for use as an Internet network number. 

18328 The inet_ntoa() function shall convert the Internet host address specified by in to a string in the 

18329 Internet standard dot notation. 


18330 All Internet addresses shall be returned in network order (bytes ordered from left to right). 

18331 Values specified using IPv4 dotted decimal notation take one of the following forms: 


18332 a. b. c. d When four parts are specified, each is interpreted as a byte of data and assigned, 

18333 from left to right, to the four bytes of an Internet address. 


18334 

18335 

18336 

18337 


a. b. c When a three-part address is specified, the last part is interpreted as a 16-bit 

quantity and placed in the rightmost two bytes of the network address. This makes 
the three-part address format convenient for specifying Class B network addresses 

as 128.net.host. 


18338 

18339 

18340 

18341 


a. b When a two-part address is supplied, the last part is interpreted as a 24-bit 

quantity and placed in the rightmost three bytes of the network address. This 
makes the two-part address format convenient for specifying Class A network 
addresses as net.host. 


18342 a When only one part is given, the value is stored directly in the network address 

18343 without any byte rearrangement. 


18344 All numbers supplied as parts in IPv4 dotted decimal notation may be decimal, octal, or 

18345 hexadecimal, as specified in the ISOC standard (that is, a leading "Ox" or "OX" implies 

18346 hexadecimal; otherwise, a leading ' 0' implies octal; otherwise, the number is interpreted as 

18347 decimal). 
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18348 RETURN VALUE 

18349 Upon successful completion, inet_addr() shall return the Internet address. Otherwise, it shall 

18350 return (in_addr_t)(-l). 

18351 The inet_lnaof( ) function shall return the local network address part. 

18352 The inet_makeaddr( ) function shall return the constructed Internet address. 

18353 The inet_netof( ) function shall return the network number. 

18354 Upon successful completion, inet_netivork( ) shall return the converted Internet network number. 

18355 Otherwise, it shall return (in_addr_t) (-1). 

18356 The inet_ntoa() function shall return a pointer to the network address in Internet standard dot 

18357 notation. 

18358 ERRORS 

18359 No errors are defined. 

18360 EXAMPLES 

18361 None. 

18362 APPLICATION USAGE 

18363 The inet_lnaof (), inet_makenddr (), inet_netof( ), and inet_netivork( ) functions are marked LEGACY 

18364 and should not be used by new applications. 

18365 The return value of inet_ntoa() may point to static data that may be overwritten by subsequent 

18366 calls to inet_ntoa(). 

18367 RATIONALE 

18368 None. 

18369 FUTURE DIRECTIONS 

18370 The inet_lnaof( ), inet_makeaddr( ), inet_netof( ), and inet_netivork( ) functions may be withdrawn in 

18371 a future issue. 

18372 SEE ALSO 

18373 endhostent(), endnetent(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

18374 <arpa/inet.h> 

18375 CHANGE HISTORY 

18376 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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18377 NAME 

18378 inct lnaof — IPv4 address manipulation 

18379 SYNOPSIS 

18380 tinclude <arpa/inet. h> 

18381 in_addr_t inet_lnaof (struct in_addr in); 

18382 DESCRIPTION 

18383 Refer to inet_addr (). 
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18384 NAME 

18385 inet_makeaddr — IPv4 address manipulation 

18386 SYNOPSIS 

18387 tinclude <arpa/inet. h> 

18388 struct in_addr inet_makeaddr (in_addr_t net, in_addr 

18389 DESCRIPTION 

18390 Refer to inet_addr (). 


Ina) ; 
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18391 NAME 

18392 inet_netof — IPv4 address manipulation 

18393 SYNOPSIS 

18394 tinclude <arpa/inet. h> 

18395 in_addr_t inet_netof (struct in_addr in); 

18396 DESCRIPTION 

18397 Refer to inet_addr (). 


System Interfaces, Issue 6 


583 




inet_network() 


System Interfaces 


18398 NAME 

18399 inet_network — IPv4 address manipulation 

18400 SYNOPSIS 

18401 tinclude <arpa/inet. h> 

18402 in_addr_t inet_network (const char * cp) ; 

18403 DESCRIPTION 

18404 Refer to inet_addr (). 
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18405 NAME 

18406 inet_ntoa — IPv4 address manipulation 

18407 SYNOPSIS 

18408 tinclude <arpa/inet. h> 

18409 char *inet_ntoa(struct in_addr in); 

18410 DESCRIPTION 

18411 Refer to inet_addr (). 
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18412 NAME 

18413 inet_ntop, inet_pton — convert IPv4 and IPv6 addresses between binary and text form 

18414 SYNOPSIS 

18415 IP6 #include <arpa/inet . h> 

18416 

18417 

18418 

18419 

18420 DESCRIPTION 

18421 The inet_ntop() function converts a numeric address into a text string suitable for presentation. 

18422 The af argument specifies the family of the address. This can be AF_INET or AF_INET6. The src 

18423 argument points to a buffer holding an IPv4 address if the af argument is AF_INET, or an IPv6 

18424 address if the af argument is AF_INET6. The dst argument points to a buffer where the function 

18425 stores the resulting text string; it shall not be NUEL. The size argument specifies the size of this 

18426 buffer, which shall be large enough to hold the text string (INET_ADDRSTREEN characters for 

18427 IPv4, INET6_ADDRSTREEN characters for IPv6). 

18428 The inet_pton() function converts an address in its standard text presentation form into its 

18429 numeric binary form. The af argument specifies the family of the address. The AF_INET and 

18430 AF_INET6 address families are supported. The src argument points to the string being passed in. 

18431 The dst argument points to a buffer into which the function stores the numeric address; this shall 

18432 be large enough to hold the numeric address (32 bits for AF_INET, 128 bits for AF_INET6). 

18433 If the af argument of inetjpton () is AF_INET, the src string shall be in the standard IPv4 dotted- 

18434 decimal form: 

18435 ddd. ddd. ddd. ddd 

18436 where "ddd" is a one to three digit decimal number between 0 and 255 (see inet_addr()). The 

18437 inetjpton () function does not accept other formats (such as the octal numbers, hexadecimal 

18438 numbers, and fewer than four numbers that inet_addr( ) accepts). 

18439 If the af argument of inetjpton () is AF_INET6, the src string shall be in one of the following 

18440 standard IPv6 text forms: 

18441 1. The preferred form is " x : x : x : x : x : x : x : x ", where the ' x ' s are the hexadecimal values 

18442 of the eight 16-bit pieces of the address, heading zeros in individual fields can be omitted, 

18443 but there shall be at least one numeral in every field. 

18444 2. A string of contiguous zero fields in the preferred form can be shown as ": :The ": :" 

18445 can only appear once in an address. Unspecified addresses ("0:0:0:0:0:0:0:0") may 

18446 be represented simply as ": :". 

18447 3. A third form that is sometimes more convenient when dealing with a mixed environment 

18448 of IPv4 and IPv6 nodes is "x:x:x:x:x:x:d.d.d.d", where the ' x ' s are the 

18449 hexadecimal values of the six high-order 16-bit pieces of the address, and the ' d' s are the 

18450 decimal values of the four low-order 8-bit pieces of the address (standard IPv4 

18451 representation). 

18452 Note: A more extensive description of the standard representations of IPv6 addresses can 

18453 be found in RFC 2373. 


const char *inet_ntop(int af, const void *src, char *dst, 
socklen_t size) ; 

int inet_pton(int af, const char *src, void *dst); 
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RETURN VALUE 

The inet_ntop() function shall return a pointer to the buffer containing the text string if the 
conversion succeeds, and NULL otherwise. 

The inetjpton () function shall return 1 if the conversion succeeds, with the address pointed to by 
dst in network byte order. It shall return 0 if the input is not a valid IPv4 dotted-decimal string or 
a valid IPv6 address string, or -1 with errno set to [EAFNOSUPPORT] if the af argument is 
unknown. 

ERRORS 

The inet_ntop() and inetjpton {) functions shall fail if: 

[EAFNOSUPPORT] 

The af argument is invalid. 

[ENOSPC] The size of the inet_ntop () result buffer is inadequate. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

The System Interface Definitions volume of IEEE Std. 1003.1-200x, <arpa/inet.h> 

CHANGE HISTORY 

First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 

Marked as part of the IPv6 option. 
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18479 

18480 

18481 

18482 

18483 

18484 

18485 

18486 

18487 

18488 

18489 

18490 

18491 

18492 

18493 

18494 

18495 

18496 

18497 

18498 

18499 

18500 

18501 

18502 

18503 

18504 

18505 

18506 

18507 

18508 

18509 

18510 

18511 

18512 

18513 

18514 

18515 

18516 

18517 

18518 

18519 

18520 


NAME 

initstate, random, setstate, srandom — pseudorandom number functions 

SYNOPSIS 

xsi tinclude <stdlib.h> 

char *initstate(unsigned int seed, char *state, size_t size ); 
long random(void); 

char *setstate(const char * state ); 
void srandom(unsigned int seed); 


DESCRIPTION 

The random () function uses a non-linear additive feedback random-number generator 
employing a default state array size of 31 long integers to return successive pseudo-random 
numbers in the range from 0 to 2 31 -1. The period of this random-number generator is 
approximately 16 x (2 31 -1). The size of the state array determines the period of the random- 
number generator. Increasing the state array size increases the period. 

With 256 bytes of state information, the period of the random-number generator is greater than 

269 

Like rand{), random () produces by default a sequence of numbers that can be duplicated by 
calling srandom () with 1 as the seed. 

The srandom () function initializes the current state array using the value of seed. 

The initstate() and setstate( ) functions handle restarting and changing random-number 
generators. The initstate() function allows a state array, pointed to by the state argument, to be 
initialized for future use. The size argument, which specifies the size in bytes of the state array, is 
used by initstate{) to decide what type of random-number generator to use; the larger the state 
array, the more random the numbers. Values for the amount of state information are 8, 32, 64, 
128, and 256 bytes. Other values greater than 8 bytes are rounded down to the nearest one of 
these values. If initstate() is called with 8<size<32, then random() uses a simple linear 
congruential random number generator. The seed argument specifies a starting point for the 
random-number sequence and provides for restarting at the same point. The initstate( ) function 
shall return a pointer to the previous state information array. 

If initstate () has not been called, then random () behaves as though initstate() had been called 
with seed= 1 and size=128. 

Once a state has been initialized, setstate () allows switching between state arrays. The array 
defined by the state argument is used for further random-number generation until initstate() is 
called or setstate( ) is called again. The setstate( ) function shall return a pointer to the previous 
state array. 

RETURN VALUE 

If initstate( ) is called with size less than 8, it shall return NULL. 

The random () function shall return the generated pseudo-random number. 

The srandom () function shall return no value. 

Upon successful completion, initstate () and setstate( ) shall return a pointer to the previous state 
array; otherwise, a null pointer shall be returned. 
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18521 

18522 

18523 

18524 

18525 

18526 

18527 

18528 

18529 

18530 

18531 

18532 

18533 

18534 

18535 

18536 

18537 

18538 

18539 

18540 

18541 

18542 

18543 

18544 

18545 

18546 

18547 

18548 

18549 

18550 

18551 

18552 


ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

After initialization, a state array can be restarted at a different point in one of two ways: 

1. The initstate() function can be used, with the desired seed, state array, and size of the 
array. 

2. The setstate( ) function, with the desired state, can be used, followed by srandom() with the 
desired seed. The advantage of using both of these functions is that the size of the state 
array does not have to be saved once it is initialized. 

Although some implementations of random () have written messages to standard error, such 
implementations do not conform to this volume of IEEE Std. 1003.1-200x. 

Issue 5 restores the historical behavior of this function. 

Threaded applications should use rand_r(), erand48(), nrand48 (), or jrand48() instead of 
random () when an independent random number sequence in multiple threads is required. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

drand48(), rand( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 

In the DESCRIPTION, the phrase "values smaller than 8" is replaced with "values greater than 
or equal to 8, or less than 32", "size<8 " is replaced with "8 <size <32", and a new first paragraph 
is added to the RETURN VALUE section. A note is added to the APPLICATION USAGE 
indicating that these changes restore the historical behavior of the function. 

Issue 6 

In the DESCRIPTION, duplicate text "For values greater than or equal to 8 ..." is removed. 
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18557 

18558 

18559 

18560 

18561 
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18563 

18564 

18565 

18566 
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18578 

18579 

18580 

18581 

18582 

18583 

18584 

18585 

18586 

18587 

18588 

18589 

18590 

18591 

18592 

18593 

18594 
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NAME 

insque, remque — insert or remove an element in a queue 

SYNOPSIS 

xsi tinclude <search.h> 

void insque(void * element, void *pred ); 
void remque(void * element ); 


DESCRIPTION 

The insqueO and remque() functions manipulate queues built from doubly-linked lists. The 
queue can be either circular or linear. An application using insque () or remque () shall ensure it I 
defines a structure in which the first two members of the structure are pointers to the same type I 
of structure, and any further members are application-specific. The first member of the structure I 
is a forward pointer to the next entry in the queue. The second member is a backward pointer to I 
the previous entry in the queue. If the queue is linear, the queue is terminated with null I 
pointers. The names of the structure and of the pointer members are not subject to any special I 
restriction. I 

The insque( ) function inserts the element pointed to by element into a queue immediately after 
the element pointed to by pred. 

The remque () function removes the element pointed to by element from a queue. 

If the queue is to be used as a linear list, invoking insque(&celement, NULL), where element is the 
initial element of the queue, shall initialize the forward and backward pointers of element to null 
pointers. 

If the queue is to be used as a circular list, the application shall ensure it initializes the forward I 
pointer and the backward pointer of the initial element of the queue to the element's own I 
address. I 

RETURN VALUE 

The insque( ) and remque () functions do not return a value. 

ERRORS 

No errors are defined. 

EXAMPLES 

Creating a Linear Linked List 

The following example creates a linear linked list. 

#include <search.h> 

struct myque elementl; 
struct myque element2; 

char *datal = "DATA1"; 
char *data2 = "DATA2"; 

element 1.data = datal; 
element2.data = data2; 

insque (Selementl, NULL); 
insque (&element2, Selementl); 
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18596 Creating a Circular Linked List 

18597 The following example creates a circular linked list. 

18598 #include <search.h> 

18599 

18600 struct myque elementl; 

18601 struct myque element2; 

18602 char *datal = "DATA1"; 

18603 char *data2 = "DATA2"; 

18604 

18605 element 1. data = datal; 

18606 element2 . data = data2; 

18607 element l.fwd = Selementl; 

18608 elementl.bck = Selementl; 

18609 insque (&element2, Selementl); 

18610 Removing an Element 

18611 The following example removes the element pointed to by elementl. 

18612 #include <search.h> 

18613 

18614 struct myque elementl; 

18615 

18616 remque (Selementl); 

18617 APPLICATION USAGE 

18618 The historical implementations of these functions described the arguments as being of type 

18619 struct qelem* rather than as being of type void* as defined here. In those implementations, 

18620 struct qelem was commonly defined in <search.h> as: 

18621 struct qelem { 

18622 struct qelem *q_forw; 

18623 struct qelem *q_back; 

18624 }; 

18625 Applications using these functions, however, were never able to use this structure directly since 

18626 it provided no room for the actual data contained in the elements. Most applications defined 

18627 structures that contained the two pointers as the initial elements and also provided space for, or 

18628 pointers to, the object's data. Applications that used these functions to update more than one 

18629 type of table also had the problem of specifying two or more different structures with the same 

18630 name, if they literally used struct qelem as specified. 

18631 As described here, the implementations were actually expecting a structure type where the first 

18632 two members were forward and backward pointers to structures. With C compilers that didn't 

18633 provide function prototypes, applications used structures as specified in the DESCRIPTION 

18634 above and the compiler did what the application expected. 

18635 If this method had been carried forward with an ISO C standard compiler and the historical 

18636 function prototype, most applications would have to be modified to cast pointers to the 

18637 structures actually used to be pointers to struct qelem to avoid compilation warnings. By 

18638 specifying void* as the argument type, applications do not need to change (unless they 

18639 specifically referenced struct qelem and depended on it being defined in <search.h>). 
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18640 RATIONALE 

18641 None. 

18642 FUTURE DIRECTIONS 

18643 None. 

18644 SEE ALSO 

18645 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <search.h> 

18646 CHANGE HISTORY 

18647 First released in Issue 4, Version 2. 

18648 Issue 5 

18649 Moved from X/OPEN UNIX extension to BASE. 

18650 Issue 6 

18651 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 


592 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


ioctl() 


18652 NAME 

18653 ioctl — control a STREAMS device (STREAMS) 

18654 SYNOPSIS 

18655 XSR tinclude <stropts.h> 

18656 int ioctl (int fildes, int request, ... /* arg */); 

18657 

18658 DESCRIPTION 

18659 The ioctl () function performs a variety of control functions on STREAMS devices. For non- 

18660 STREAMS devices, the functions performed by this call are unspecified. The request argument 

18661 and an optional third argument (with varying type) are passed to and interpreted by the 

18662 appropriate part of the STREAM associated with//Wes. 

18663 The fildes argument is an open file descriptor that refers to a device. 

18664 The request argument selects the control function to be performed and shall depend on the 

18665 STREAMS device being addressed. 

18666 The arg argument represents additional information that is needed by this specific STREAMS 

18667 device to perform the requested function. The type of arg depends upon the particular control 

18668 request, but it is either an integer or a pointer to a device-specific data structure. 

18669 The ioctl () commands applicable to STREAMS, their arguments, and error conditions that apply 

18670 to each individual command are described below. 

18671 The following ioctl () commands, with error values indicated, are applicable to all STREAMS 

18672 files: 


18673 I_PUSH 

18674 

18675 

18676 

18677 

18678 

18679 

18680 I_POP 

18681 

18682 

18683 

18684 


Pushes the module whose name is pointed to by arg onto the top of the 
current STREAM, just below the STREAM head. It then calls the open() 
function of the newly-pushed module. 

The ioctl () function with the I_PUSH command shall fail if: 

[EINVAL] Invalid module name. 

[ENXIO] Open function of new module failed. 

[ENXIO] Hangup received on fildes. 

Removes the module just below the STREAM head of the STREAM pointed to 
by fildes . The arg argument should be 0 in an I_POP request. 

The ioctl () function with the I_POP command shall fail if: 

[EINVAL] No module present in the STREAM. 

[ENXIO] Hangup received on fildes . 


18685 I_LOOK Retrieves the name of the module just below the STREAM head of the 

18686 STREAM pointed to by fildes, and places it in a character string pointed to by 

18687 arg. The buffer pointed to by arg should be at least FMNAMESZ+1 bytes long, 

18688 where FMNAMESZ is defined in <stropts.h>. 


18689 


The ioctl () function with the I_LOOK command shall fail if: 


18690 


[EINVAL] No module present in the STREAM. 


18691 I_FLUSH This request flushes read and/or write queues, depending on the value of arg. 

18692 Valid arg values are: 
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18693 

18694 

18695 

18696 

18697 

18698 

18699 

18700 

18701 

18702 

18703 

18704 

18705 

18706 

18707 

18708 

18709 

18710 

18711 

18712 

18713 

18714 

18715 

18716 

18717 

18718 

18719 

18720 

18721 

18722 

18723 

18724 

18725 

18726 

18727 

18728 

18729 

18730 

18731 

18732 

18733 

18734 

18735 

18736 


FLUSHR Flush all read queues. 

FLUSHW Flush all write queues. 

FLUSHRW Flush all read and all write queues. 

The ioctl () function with the I_FLUSH command shall fail if: 

[EINVAL] Invalid arg value. 

[EAGAIN] or [ENOSR] 

Unable to allocate buffers for flush message. 

[ENXIO] Hangup received on fildes. 

I_FLUSHBAND Flushes a particular band of messages. The arg argument points to a bandinfo 
structure. The bi_flag member may be one of FLUSHR, FLUSHW, or 
FLUSHRW as described above. The bijpri member determines the priority 
band to be flushed. 


LSETSIG 


Requests that the STREAMS implementation send the SIGPOLL signal to the 
calling process when a particular event has occurred on the STREAM 
associated with fildes. I_SETSIG supports an asynchronous processing 
capability in STREAMS. The value of arg is a bitmask that specifies the events 
for which the process should be signaled. It is the bitwise-inclusive OR of any 
combination of the following constants: 


S_RDNORM 

S_RDBAND 

S_INPUT 

S_HIPRI 

S_OUTPUT 

S_WRNORM 

S_WRBAND 

S_MSG 

S_ERROR 


A normal (priority band set to 0) message has arrived at the 
head of a STREAM head read queue. A signal shall be 
generated even if the message is of zero length. 

A message with a non-zero priority band has arrived at the 
head of a STREAM head read queue. A signal shall be 
generated even if the message is of zero length. 

A message, other than a high-priority message, has arrived 
at the head of a STREAM head read queue. A signal shall be 
generated even if the message is of zero length. 

A high-priority message is present on a STREAM head read 
queue. A signal shall be generated even if the message is of 
zero length. 

The write queue for normal data (priority band 0) just 
below the STREAM head is no longer full. This notifies the 
process that there is room on the queue for sending (or 
writing) normal data downstream. 

Same as S_OUTPUT. 

The write queue for a non-zero priority band just below the 
STREAM head is no longer full. This notifies the process 
that there is room on the queue for sending (or writing) 
priority data downstream. 

A STREAMS signal message that contains the SIGPOLL 
signal has reached the front of the STREAM head read 
queue. 

Notification of an error condition has reached the STREAM 
head. 
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18741 

18742 

18743 

18744 

18745 

18746 

18747 

18748 

18749 

18750 

18751 

18752 

18753 

18754 

18755 

18756 

18757 

18758 

18759 

18760 

18761 

18762 

18763 

18764 

18765 
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I_GETSIG 


I_FIND 


I_PEEK 


I_SRDOPT 


S_HANGUP Notification of a hangup has reached the STREAM head. 

S_BANDURG When used in conjunction with S_RDBAND, SIGURG is 
generated instead of SIGPOLL when a priority message 
reaches the front of the STREAM head read queue. 

If arg is 0, the calling process shall be unregistered and shall not receive 
further SIGPOLL signals for the stream associated with fildes. 

Processes that wish to receive SIGPOLL signals shall ensure that they I 
explicitly register to receive them using I_SETSIG. If several processes register I 
to receive this signal for the same event on the same STREAM, each process I 
shall be signaled when the event occurs. 

The ioctl () function with the I_SETSIG command shall fail if: 

[EINVAL] The value of arg is invalid. 

[EINVAL] The value of arg is 0 and the calling process is not registered 

to receive the SIGPOLL signal. 

[EAGAIN] There were insufficient resources to store the signal request. 

Returns the events for which the calling process is currently registered to be 
sent a SIGPOLL signal. The events are returned as a bitmask in an int pointed 
to by arg, where the events are those specified in the description of I_SETSIG 
above. 

The ioctl () function with the I_GETSIG command shall fail if: 

[EINVAL] Process is not registered to receive the SIGPOLL signal. 

This request compares the names of all modules currently present in the 
STREAM to the name pointed to by arg, and returns 1 if the named module is 
present in the STREAM, or returns 0 if the named module is not present. 

The ioctl () function with the I_FIND command shall fail if: 

[EINVAL] arg does not contain a valid module name. 

This request allows a process to retrieve the information in the first message 
on the STREAM head read queue without taking the message off the queue. It 
is analogous to getmsg() except that this command does not remove the 
message from the queue. The arg argument points to a strpeek structure. 

The application shall ensure that the maxlen member in the ctlbuf and databuf I 
strbuf structures is set to the number of bytes of control information and/or I 
data information, respectively, to retrieve. The flags member may be marked I 
RS_HIPRI or 0, as described by getmsg (). If the process sets flags to RS_HIPRI, 
for example, I_PEEK shall only look for a high-priority message on the 
STREAM head read queue. 

I_PEEK returns 1 if a message was retrieved, and returns 0 if no message was 
found on the STREAM head read queue, or if the RS_HIPRI flag was set in 
flags and a high-priority message was not present on the STREAM head read 
queue. It does not wait for a message to arrive. On return, ctlbuf specifies 
information in the control buffer, databuf specifies information in the data 
buffer, and flags contains the value RS_HIPRI or 0. 

Sets the read mode using the value of the argument arg. Read modes are 
described in read(). Valid arg flags are: 
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18781 

18782 

18783 

18784 

18785 

18786 

18787 

18788 

18789 

18790 

18791 

18792 

18793 

18794 

18795 

18796 

18797 

18798 

18799 

18800 
18801 
18802 

18803 

18804 

18805 

18806 

18807 

18808 

18809 

18810 
18811 
18812 

18813 

18814 

18815 

18816 

18817 

18818 

18819 

18820 
18821 
18822 

18823 

18824 

18825 


RNORM Byte-stream mode, the default. 

RMSGD Message-discard mode. 

RMSGN Message-nondiscard mode. 

The bitwise-inclusive OR of RMSGD and RMSGN shall return [EINVAL]. The 
bitwise-inclusive OR of RNORM and either RMSGD or RMSGN shall result in 
the other flag overriding RNORM which is the default. 

In addition, treatment of control messages by the STREAM head may be 
changed by setting any of the following flags in arg: 

RPROTNORM Fail read() with [EBADMSG] if a message containing a 
control part is at the front of the STREAM head read queue. 

RPROTDAT Deliver the control part of a message as data when a 
process issues a read{). 

RPROTDIS Discard the control part of a message, delivering any data 

portion, when a process issues a read (). 

The ioctl () function with the I_SRDOPT command shall fail if: 

[EINVAL] The arg argument is not valid. 

I_GRDOPT Returns the current read mode setting as, described above, in an int pointed to 
by the argument arg. Read modes are described in read(). 

I_NREAD Counts the number of data bytes in the data part of the first message on the 

STREAM head read queue and places this value in the int pointed to by arg. 
The return value for the command is the number of messages on the STREAM 
head read queue. For example, if 0 is returned in arg, but the ioctl () return 
value is greater than 0, this indicates that a zero-length message is next on the 
queue. 

I_FDINSERT Creates a message from specified buffer(s), adds information about another 
STREAM, and sends the message downstream. The message contains a 
control part and an optional data part. The data and control parts to be sent 
are distinguished by placement in separate buffers, as described below. The 
arg argument points to a strfdinsert structure. 

The application shall ensure that the len member in the ctlbuf strbuf structure I 
is set to the size of a t_uscalar_t plus the number of bytes of control I 
information to be sent with the message. Thefildes member specifies the file 
descriptor of the other STREAM, and the offset member, which must be 
suitably aligned for use as a t_uscalar_t, specifies the offset from the start of 
the control buffer where I_FDINSERT shall store a t_uscalar_t whose I 
interpretation is specific to the STREAM end. The application shall ensure that I 
the len member in the databuf strbuf structure is set to the number of bytes of I 
data information to be sent with the message, or to 0 if no data part is to be I 
sent. I 

The flags member specifies the type of message to be created. A normal 
message is created if flags is set to 0, and a high-priority message is created if 
flags is set to RS_HIPRI. For non-priority messages, I_FDINSERT shall block if 
the STREAM write queue is full due to internal flow control conditions. For 
priority messages, I_FDINSERT does not block on this condition. For non¬ 
priority messages, I_FDINSERT does not block when the write queue is full 
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18826 


and 0_N0NBL0CK is set. Instead, it fails and sets errno to [EAGAIN]. 

18827 

18828 

18829 

18830 


I_FDINSERT also blocks, unless prevented by lack of internal resources, 
waiting for the availability of message blocks in the STREAM, regardless of 
priority or whether 0_NONBLOCK has been specified. No partial message is 
sent. 

18831 


The ioctl () function with the I_FDINSERT command shall fail if: 

18832 

18833 

18834 


[EAGAIN] 

A non-priority message is specified, the 0_NONBLOCK 
flag is set, and the STREAM write queue is full due to 
internal flow control conditions. 

18835 

18836 

18837 


[EAGAIN] or [ENOSR] 

Buffers cannot be allocated for the message that is to be 
created. 

18838 


[EINVAL] 

One of the following: 

18839 

18840 



— Th e fildes member of the strfdinsert structure is not a 
valid, open STREAM file descriptor. 

18841 

18842 



— The size of a t_uscalar_t plus offset is greater than the len 
member for the buffer specified through ctlbuf. 

18843 

18844 



— The offset member does not specify a properly-aligned 
location in the data buffer. 

18845 



— An undefined value is stored in flags. 

18846 

18847 

18848 


[ENXIO] 

Hangup received on the STREAM identified by either the 
fildes argument or the fildes member of the strfdinsert 
structure. 

18849 

18850 

18851 

18852 

18853 

18854 

18855 

18856 


[ERANGE] 

The len member for the buffer specified through databuf 
does not fall within the range specified by the maximum 
and minimum packet sizes of the topmost STREAM module 
or the len member for the buffer specified through databuf 
is larger than the maximum configured size of the data part 
of a message; or the len member for the buffer specified 
through ctlbuf is larger than the maximum configured size 
of the control part of a message. 

18857 

18858 

I_STR 

Constructs an internal STREAMS ioctl () message from the data pointed to by 
arg, and sends that message downstream. 

18859 

18860 

18861 

18862 

18863 

18864 


This mechanism is provided to send ioctl () requests to downstream modules 
and drivers. It allows information to be sent with ioctl (), and returns to the 
process any information sent upstream by the downstream recipient. I_STR 
blocks until the system responds with either a positive or negative 
acknowledgement message, or until the request times out after some period of 
time. If the request times out, it fails with errno set to [ETIME], 

18865 

18866 

18867 

18868 


At most, one I_STR can be active on a STREAM. Further I_STR calls shall 
block until the active I_STR completes at the STREAM head. The default 
timeout interval for these requests is 15 seconds. The 0_NONBLOCK flag has 
no effect on this call. 

18869 

18870 


To send requests downstream, the application shall ensure that arg points to a 
strioctl structure. 
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18871 

18872 

18873 

18874 

18875 

18876 

18877 

18878 

18879 

18880 


The ic_cmd member is the internal ioctl() command intended for a 
downstream module or driver and icjimont is the number of seconds 
(-l=infinite, 0=use implementation-dependent timeout interval, >0=as 
specified) an I_STR request shall wait for acknowledgement before timing out. 
icjen is the number of bytes in the data argument, and ic_dp is a pointer to the 
data argument. The icjen member has two uses: on input, it contains the 
length of the data argument passed in, and on return from the command, it 
contains the number of bytes being returned to the process (the buffer pointed 
to by ic_dp should be large enough to contain the maximum amount of data 
that any module or the driver in the STREAM can return). 

18881 

18882 


The STREAM head shall convert the information pointed to by the strioctl 
structure to an internal ioctl () command message and sends it downstream. 

18883 


The ioctl () function with the I_STR command shall fail if: 

18884 

18885 


[EAGAIN] or [ENOSR] 

Unable to allocate buffers for the ioctl () message. 

18886 

18887 

18888 


[EINVAL] The icjen member is less than 0 or larger than the 

maximum configured size of the data part of a message, or 
icjimout is less than -1. 

18889 


[ENXIO] Hangup received on fildes. 

18890 

18891 


[ETIME] A downstream ioctl () timed out before acknowledgement 

was received. 

18892 

18893 

18894 

18895 

18896 


An I_STR can also fail while waiting for an acknowledgement if a message 
indicating an error or a hangup is received at the STREAM head. In addition, 
an error code can be returned in the positive or negative acknowledgement 
message, in the event the ioctl () command sent downstream fails. For these 
cases, I_STR fails with errno set to the value in the message. 

18897 

18898 

I_SWROPT 

Sets the write mode using the value of the argument arg. Valid bit settings for 
arg are: 

18899 

18900 

18901 

18902 


SNDZERO Send a zero-length message downstream when a ivrite( ) of 

0 bytes occurs. To not send a zero-length message when a 
write( ) of 0 bytes occurs, the application shall ensure that 
this bit is not set in arg (for example, arg would be set to 0). 

18903 


The ioctl () function with the I_SVVROPT command shall fail if: 

18904 


[EINVAL] arg is not the above value. 

18905 

18906 

I_GWROPT 

Returns the current write mode setting, as described above, in the int that is 
pointed to by the argument arg. 

18907 

18908 

18909 

18910 

I_SENDFD 

I_SENDFD creates a new reference to the open file description associated with 
the file descriptor arg, and writes a message on the STREAMS-based pipe 
fildes containing this reference, together with the user ID and group ID of the 
calling process. 

18911 


The ioctl () function with the I_SENDFD command shall fail if: 

18912 

18913 

18914 

18915 


[EAGAIN] The sending STREAM is unable to allocate a message block 

to contain the file pointer; or the read queue of the receiving 
STREAM head is full and cannot accept the message sent by 
I_SENDFD. 
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[EBADF] The arg argument is not a valid, open file descriptor. 

18917 


[EINVAL] The fildes argument is not connected to a STREAM pipe. 

18918 


[ENXIO] Hangup received on fildes. 

18919 

18920 

18921 

18922 

18923 

HRECVFD 

Retrieves the reference to an open file description from a message written to a 
STREAMS-based pipe using the I_SENDFD command, and allocates a new 
file descriptor in the calling process that refers to this open file description. 
The arg argument is a pointer to a strrecvfd data structure as defined in 

<stropts.h>. 

18924 

18925 


The/d member is a file descriptor. The uid and gid members are the effective 
user ID and effective group ID, respectively, of the sending process. 

18926 

18927 

18928 


If 0_N0NBL0CK is not set, HRECVFD blocks until a message is present at 
the STREAM head. If 0_N0NBL0CK is set, HRECVFD fails with errno set to 
[E AG AIN] if no message is present at the STREAM head. 

18929 

18930 

18931 

18932 


If the message at the STREAM head is a message sent by an I_SENDFD, a new 
file descriptor is allocated for the open file descriptor referenced in the 
message. The new file descriptor is placed in the fd member of the strrecvfd 
structure pointed to by arg. 

18933 


The iodl () function with the I_RECVFD command shall fail if: 

18934 

18935 


[EAGAIN] A message is not present at the STREAM head read queue 

and the 0_N0NBL0CK flag is set. 

18936 

18937 


[EBADMSG] The message at the STREAM head read queue is not a 

message containing a passed file descriptor. 

18938 

18939 


[EMFILE] The process has the maximum number of file descriptors 

currently open that it is allowed. 

18940 


[ENXIO] Hangup received on fildes. 

18941 

18942 

18943 

18944 

18945 

I.LIST 

This request allows the process to list all the module names on the STREAM, 
up to and including the topmost driver name. If arg is a null pointer, the 
return value is the number of modules, including the driver, that are on the 
STREAM pointed to by fildes. This lets the process allocate enough space for 
the module names. Otherwise, it should point to a str_list structure. 

18946 

18947 

18948 

18949 

18950 

18951 

18952 

18953 


The sl_nmods member indicates the number of entries the process has 
allocated in the array. Upon return, the sl_modIist member of the str list 
structure contains the list of module names, and the number of entries that 
have been filled into the sl_modlist array is found in the sl_nmods member (the 
number includes the number of modules including the driver). The return 
value from ioctl() is 0. The entries are filled in starting at the top of the 
STREAM and continuing downstream until either the end of the STREAM is 
reached, or the number of requested modules ( sl_nmods ) is satisfied. 

18954 


The ioctl () function with the I_LIST command shall fail if: 

18955 


[EINVAL] The sl_nmods member is less than 1. 

18956 

18957 


[EAGAIN] or [ENOSR] 

Unable to allocate buffers. 

18958 

18959 

I_ATMARK 

This request allows the process to see if the message at the head of the 
STREAM head read queue is marked by some module downstream. The arg 
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18960 

18961 

18962 


argument determines how the checking is done when there may be multiple 
marked messages on the STREAM head read queue. It may take on the 
following values: 

18963 


ANYMARK Check if the message is marked. 

18964 


LASTMARK Check if the message is the last one marked on the queue. 

18965 

18966 


The bitwise-inclusive OR of the flags ANYMARK and LASTMARK is 
permitted. 

18967 

18968 


The return value is 1 if the mark condition is satisfied; otherwise, the value is 
0. 

18969 


The ioctl () function with the I_ATMARK command shall fail if: 

18970 


[EINVAL] Invalid arg value. 

18971 

18972 

18973 

I_CKBAND 

Check if the message of a given priority band exists on the STREAM head 
read queue. This returns 1 if a message of the given priority exists, 0 if no such 
message exists, or -1 on error, arg should be of type int. 

18974 


The ioctl () function with the I_CKBAND command shall fail if: 

18975 


[EINVAL] Invalid arg value. 

18976 

18977 

I_GETBAND 

Return the priority band of the first message on the STREAM head read queue 
in the integer referenced by arg. 

18978 


The ioctl () function with the I_GETBAND command shall fail if: 

18979 


[ENODATA] No message on the STREAM head read queue. 

18980 

18981 

18982 

I_CANPUT 

Check if a certain band is writable, arg is set to the priority band in question. 
The return value is 0 if the band is flow-controlled, 1 if the band is writable, or 
-1 on error. 

18983 


The ioctl () function with the I_CANPUT command shall fail if: 

18984 


[EINVAL] Invalid arg value. 

18985 

18986 

18987 

18988 

18989 

18990 

18991 

18992 

I_SETCLTIME 

This request allows the process to set the time the STREAM head shall delay 
when a STREAM is closing and there is data on the write queues. Before 
closing each module or driver, if there is data on its write queue, the STREAM 
head shall delay for the specified amount of time to allow the data to drain. If, 
after the delay, data is still present, it shall be flushed. The arg argument is a 
pointer to an integer specifying the number of milliseconds to delay, rounded 
up to the nearest valid value. If I_SETCLTIME is not performed on a STREAM, 
an implementation-dependent default timeout interval is used. 

18993 


The ioctl () function with the I_SETCLTIME command shall fail if: 

18994 


[EINVAL] Invalid arg value. 

18995 

I_GETCLTIME 

This request returns the close time delay in the integer pointed to by arg. 
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Multiplexed STREAMS Configurations 

The following commands are used for connecting and disconnecting multiplexed STREAMS 
configurations. These commands use an implementation-dependent default timeout interval. 

I_LINK Connects two STREAMS, where fildes is the file descriptor of the STREAM 

connected to the multiplexing driver, and arg is the file descriptor of the 
STREAM connected to another driver. The STREAM designated by arg is 
connected below the multiplexing driver. I_LINK requires the multiplexing 
driver to send an acknowledgement message to the STREAM head regarding 
the connection. This call returns a multiplexer ID number (an identifier used 
to disconnect the multiplexer; see I_UNLINK) on success, and -1 on failure. 

The ioctl () function with the I_LINK command shall fail if: 

[ENXIO] Hangup received on fildes. 

[ETIME] Timeout before acknowledgement message was received at 

STREAM head. 

[EAGAIN] or [ENOSR] 

Unable to allocate STREAMS storage to perform the 
I_LINK. 

The arg argument is not a valid, open file descriptor. 

The fildes argument does not support multiplexing; or arg is 
not a STREAM or is already connected downstream from a 
multiplexer; or the specified I_LINK operation would 
connect the STREAM head in more than one place in the 
multiplexed STREAM. 

An I_LINK can also fail while waiting for the multiplexing driver to 
acknowledge the request, if a message indicating an error or a hangup is 
received at the STREAM head of fildes . In addition, an error code can be 
returned in the positive or negative acknowledgement message. For these 
cases, I_LINK fails with errno set to the value in the message. 

I_UNLINK Disconnects the two STREAMS specified by fildes and arg. fildes is the file 
descriptor of the STREAM connected to the multiplexing driver. The arg 
argument is the multiplexer ID number that was returned by the I_LINK 
ioctl () command when a STREAM was connected downstream from the 
multiplexing driver. If arg is MUXID_ALL, then all STREAMS that were 
connected to fildes are disconnected. As in I_LINK, this command requires 
acknowledgement. 

The ioctl () function with the I_UNLINK command shall fail if: 

[ENXIO] Hangup received on fildes. 

[ETIME] Timeout before acknowledgement message was received at 

STREAM head. 

[EAGAIN] or [ENOSR] 

Unable to allocate buffers for the acknowledgement 
message. 

[EINVAL] Invalid multiplexer ID number. 


[EBADF] 

[EINVAL] 
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An I_UNLINK can also fail while waiting for the multiplexing driver to 
acknowledge the request if a message indicating an error or a hangup is 
received at the STREAM head of fildes . In addition, an error code can be 
returned in the positive or negative acknowledgement message. For these 
cases, I_UNLINK fails with errno set to the value in the message. 

I_PLINK Creates a persistent connection between two STREAMS, where fildes is the file 

descriptor of the STREAM connected to the multiplexing driver, and arg is the 
file descriptor of the STREAM connected to another driver. This call creates a 
persistent connection which can exist even if the file descriptor fildes 
associated with the upper STREAM to the multiplexing driver is closed. The 
STREAM designated by arg gets connected via a persistent connection below 
the multiplexing driver. I_PLINK requires the multiplexing driver to send an 
acknowledgement message to the STREAM head. This call returns a 
multiplexer ID number (an identifier that may be used to disconnect the 
multiplexer; see I_PUNLINK) on success, and -1 on failure. 

The ioctl () function with the I_PLINK command shall fail if: 

[ENXIO] Hangup received on fildes. 

[ETIME] Timeout before acknowledgement message was received at 

STREAM head. 

[EAGAIN] or [ENOSR] 

Unable to allocate STREAMS storage to perform the 
UPLINK. 

[EBADF] The arg argument is not a valid, open file descriptor. 

[EINVAL] Th e fildes argument does not support multiplexing; or arg is 

not a STREAM or is already connected downstream from a 
multiplexer; or the specified I_PLINK operation would 
connect the STREAM head in more than one place in the 
multiplexed STREAM. 

An UPLINK can also fail while waiting for the multiplexing driver to 
acknowledge the request, if a message indicating an error or a hangup is 
received at the STREAM head of fildes . In addition, an error code can be 
returned in the positive or negative acknowledgement message. For these 
cases, UPLINK fails with errno set to the value in the message. 

I_PUNLINK Disconnects the two STREAMS specified by fildes and arg from a persistent 
connection. The fildes argument is the file descriptor of the STREAM 
connected to the multiplexing driver. The arg argument is the multiplexer ID 
number that was returned by the UPLINK ioctl () command when a STREAM 
was connected downstream from the multiplexing driver. If arg is 
MUXID_ALL, then all STREAMS which are persistent connections to fildes are 
disconnected. As in UPLINK, this command requires the multiplexing driver 
to acknowledge the request. 

The ioctl () function with the UPUNLINK command shall fail if: 

[ENXIO] Hangup received on fildes. 

[ETIME] Timeout before acknowledgement message was received at 

STREAM head. 
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[EAGAIN] or [ENOSR] 

Unable to allocate buffers for the acknowledgement 
message. 


19087 


[EINVAL] Invalid multiplexer ID number. 


19088 

19089 

19090 

19091 

19092 


An I_PUNLINK can also fail while waiting for the multiplexing driver to 
acknowledge the request if a message indicating an error or a hangup is 
received at the STREAM head of fildes . In addition, an error code can be 
returned in the positive or negative acknowledgement message. For these 
cases, I_PUNLINK fails with errno set to the value in the message. 


19093 RETURN VALUE 

19094 Upon successful completion, ioctl () shall return a value other than -1 that depends upon the 

19095 STREAMS device control function. Otherwise, it shall return -1 and set errno to indicate the 

19096 error. 


19097 ERRORS 


19098 

19099 

19100 

19101 

19102 

19103 

19104 

19105 

19106 

19107 


Under the following general conditions, ioctl () shall fail if: 

[EBADF] Th e fildes argument is not a valid open file descriptor. 

[EINTR] A signal was caught during the ioctl () operation. 

[EINVAL] The STREAM or multiplexer referenced by fildes is linked (directly or 

indirectly) downstream from a multiplexer. 

If an underlying device driver detects an error, then ioctl () shall fail if: 

[EINVAL] The request or arg argument is not valid for this device. 

[EIO] Some physical I/O error has occurred. 

[ENOTTY] Th e fildes argument is not associated with a STREAMS device that accepts 

control functions. 


19108 [ENXIO] The request and arg arguments are valid for this device driver, but the service 

19109 requested cannot be performed on this particular sub-device. 


19110 [ENODEV] Th e fildes argument refers to a valid STREAMS device, but the corresponding 

19111 device driver does not support the ioctl () function. 


19112 If a STREAM is connected downstream from a multiplexer, any ioctl () command except 

19113 IJJNLINK and I_PUNLINK shall set errno to [EINVAL], 

19114 EXAMPLES 

19115 None. 

19116 APPLICATION USAGE 

19117 The implementation-dependent timeout interval for STREAMS has historically been 15 seconds. 

19118 RATIONALE 

19119 None. 

19120 FUTURE DIRECTIONS 

19121 None. 

19122 SEE ALSO 

19123 close (), fcntl(), getmsg(), open(), pipe{), poll(), putmsg(), read(), sigaction{), write{), the System 

19124 Interface Definitions volume of IEEE Std. 1003.1-200x, <stropts.h>. Section 2.6 on page 55 
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19126 

19127 

19128 

19129 

19130 

19131 

19132 

19133 


CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 

Issue 6 

The Open Group corrigenda item U028/4 has been applied, correcting text in the I_FDINSERT, 
[EINVAL] case to refer to dlbuf. 

This function is marked as part of the XSI STREAMS Option Group. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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19134 NAME 

19135 isalnum — test for an alphanumeric character 

19136 SYNOPSIS 

19137 #include <ctype.h> 

19138 int isalnum (int c) ; 

19139 DESCRIPTION 

19140 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19141 conflict between the requirements described here and the ISO C standard is unintentional. This 

19142 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 

19143 The isalnum () function tests whether c is a character of class alpha or digit in the program's 

19144 current locale; see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, 

19145 Locale. 

19146 In all cases c is an int, the value of which the application shall ensure is representable as an 

19147 unsigned char or equal to the value of the macro EOF. If the argument has any other value, the 

19148 behavior is undefined. 

19149 RETURN VALUE 

19150 The isalnum () function shall return non-zero if c is an alphanumeric character; otherwise, it shall 

19151 return 0. 

19152 ERRORS 

19153 No errors are defined. 

19154 EXAMPLES 

19155 None. 

19156 APPLICATION USAGE 

19157 To ensure applications portability, especially across natural languages, only this function and 

19158 those listed in the SEE ALSO section should be used for character classification. 

19159 RATIONALE 

19160 None. 

19161 FUTURE DIRECTIONS 

19162 None. 

19163 SEE ALSO 

19164 isalpha(), iscntrl{), isdigit(), isgraph(), islower(), isprint(), ispunct(), isspace(), isupper(), isxdigit(), 

19165 setlocale(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <ctype.h>, 

19166 <stdio.h>, the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale 

19167 CHANGE HISTORY 

19168 First released in Issue 1. 

19169 Derived from Issue 1 of the SVID. 

19170 Issue 4 

19171 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 

19172 functional differences between this issue and Issue 3. Operation in the C locale is no longer 

19173 described explicitly on this reference page. 

19174 Issue 6 

19175 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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19176 NAME 

19177 isalpha — test for an alphabetic character 

19178 SYNOPSIS 

19179 tinclude <ctype.h> 

19180 int isalpha (int c) ; 

19181 DESCRIPTION 

19182 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19183 conflict between the requirements described here and the ISO C standard is unintentional. This I 

19184 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

19185 The isalpha () function shall test whether c is a character of class alpha in the program's current I 

19186 locale; see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

19187 In all cases c is an int, the value of which the application shall ensure is representable as an I 

19188 unsigned char or equal to the value of the macro EOF. If the argument has any other value, the I 

19189 behavior is undefined. 

19190 RETURN VALUE 

19191 The isalpha () function shall return non-zero if c is an alphabetic character; otherwise, it shall 

19192 return 0. 

19193 ERRORS 

19194 No errors are defined. 

19195 EXAMPLES 

19196 None. 

19197 APPLICATION USAGE 

19198 To ensure applications portability, especially across natural languages, only this function and 

19199 those listed in the SEE ALSO section should be used for character classification. 

19200 RATIONALE 

19201 None. 

19202 FUTURE DIRECTIONS 

19203 None. 

19204 SEE ALSO 

19205 isalnum{), iscntrl(), isdigit (), isgraph(), islower(), isprint(), ispnnct{), isspace(), isupper(), 

19206 isxdigit(), setlocale(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

19207 <ctype.h>, <stdio.h>, the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter I 

19208 7, Locale I 

19209 CHANGE HISTORY 

19210 First released in Issue 1. 

19211 Derived from Issue 1 of the SVID. 

19212 Issue 4 

19213 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 

19214 functional differences between this issue and Issue 3. Operation in the C locale is no longer 

19215 described explicitly on this reference page. I 

19216 Issue 6 I 

19217 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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19218 NAME 

19219 isascii — test for a 7-bit US-ASCII character 

19220 SYNOPSIS 

19221 xsi tinclude <ctype.h> 

19222 int isascii (int c) ; 

19223 

19224 DESCRIPTION 

19225 The isascii () function tests whether c is a 7-bit US-ASCII character code. 

19226 The isascii () function is defined on all integer values. 

19227 RETURN VALUE 

19228 The isascii () function shall return non-zero if c is a 7-bit US-ASCII character code between 0 and 

19229 octal 0177 inclusive; otherwise, it shall return 0. 

19230 ERRORS 

19231 No errors are defined. 

19232 EXAMPLES 

19233 None. 

19234 APPLICATION USAGE 

19235 None. 

19236 RATIONALE 

19237 None. 

19238 FUTURE DIRECTIONS 

19239 None. 

19240 SEE ALSO 

19241 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <ctype.h> 

19242 CHANGE HISTORY 

19243 First released in Issue 1. 

19244 Derived from Issue 1 of the SVID. 
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19245 NAME 

19246 isastream — test a file descriptor (STREAMS) 

19247 SYNOPSIS 

19248 XSR tinclude <stropts.h> 

19249 int isastream (int fildes) ; 

19250 

19251 DESCRIPTION 

19252 The isastream() function shall test whether fildes, an open file descriptor, is associated with a 

19253 STREAMS-based file. 

19254 RETURN VALUE 

19255 Upon successful completion, isastreamO shall return 1 if fildes refers to a STREAMS-based file 

19256 and 0 if not. Otherwise, isastream () shall return -1 and set errno to indicate the error. 

19257 ERRORS 

19258 The isastream () function shall fail if: 

19259 [EBADF] The fildes argument is not a valid open file descriptor. 

19260 EXAMPLES 

19261 None. 

19262 APPLICATION USAGE 

19263 None. 

19264 RATIONALE 

19265 None. 

19266 FUTURE DIRECTIONS 

19267 None. 

19268 SEE ALSO 

19269 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <stropts.h> 

19270 CHANGE HISTORY 

19271 First released in Issue 4, Version 2. 

19272 Issue 5 

19273 Moved from X/OPEN UNIX extension to BASE. 
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19276 
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19300 
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19302 
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19305 

19306 

19307 

19308 

19309 

19310 

19311 

19312 

19313 


NAME 

isatty — test for a terminal device 

SYNOPSIS 

#include <unistd.h> 
int isatty(int fildes) ; 

DESCRIPTION 

The isatty () function shall test whether fildes, an open file descriptor, is associated with a 
terminal device. 

RETURN VALUE 

The isatty () function shall return 1 it fildes is associated with a terminal; otherwise, it shall return 
man 0 and may set errno to indicate the error. 

ERRORS 

The isatty () function may fail if: 

man [EBADF] Th e fildes argument is not a valid open file descriptor. 

man [ENOTTY] The fildes argument is not associated with a terminal. 

EXAMPLES 

None. 

APPLICATION USAGE 

The isatty () function does not necessarily indicate that a human being is available for interaction 
via fildes. It is quite possible that non-terminal devices are connected to the communications 
line. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

The System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The <unistd.h> header is added to the SYNOPSIS section. 

In the RETURN VALUE section, the sentence indicating that this function may set errno is 
marked as an extension. 

The errors [EBADF] and [ENOTTY] are marked as extensions. 

Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The optional setting of errno to indicate an error is added. 

• The [EBADF] and [ENOTTY] optional error conditions are added. 
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19314 NAME 

19315 iscntrl — test for a control character 

19316 SYNOPSIS 

19317 #include <ctype.h> 

19318 int iscntrl (int c) ; 

19319 DESCRIPTION 

19320 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19321 conflict between the requirements described here and the ISO C standard is unintentional. This 

19322 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 

19323 The iscntrl () function shall test whether c is a character of class cntrl in the program's current 

19324 locale; see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. 

19325 In all cases c is a type int, the value of which the application shall ensure is a character 

19326 representable as an unsigned char or equal to the value of the macro EOF. If the argument has 

19327 any other value, the behavior is undefined. 

19328 RETURN VALUE 

19329 The iscntrl () function shall return non-zero if c is a control character; otherwise, it shall return 0. 

19330 ERRORS 

19331 No errors are defined. 

19332 EXAMPLES 

19333 None. 

19334 APPLICATION USAGE 

19335 To ensure applications portability, especially across natural languages, only this function and 

19336 those listed in the SEE ALSO section should be used for character classification. 

19337 RATIONALE 

19338 None. 

19339 FUTURE DIRECTIONS 

19340 None. 

19341 SEE ALSO 

19342 isalnum(), isalplm(), isdigit (), isgraph(), islower(), isprint(), ispnnct(), isspace (), isnpper{), 

19343 isxdigit (), setlocale(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

19344 <ctype.h>, the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale 

19345 CHANGE HISTORY 

19346 First released in Issue 1. 

19347 Derived from Issue 1 of the SVID. 

19348 Issue 4 

19349 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 

19350 functional differences between this issue and Issue 3. Operation in the C locale is no longer 

19351 described explicitly on this reference page. 

19352 Issue 6 

19353 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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19354 NAME 

19355 isdigit — test for a decimal digit 

19356 SYNOPSIS 

19357 #include <ctype.h> 

19358 int isdigit (int c) ; 

19359 DESCRIPTION 

19360 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19361 conflict between the requirements described here and the ISO C standard is unintentional. This 

19362 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 

19363 The isdigit() function shall test whether c is a character of class digit in the program's current 

19364 locale; see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. 

19365 In all cases c is an int, the value of which the application shall ensure is a character representable 

19366 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, 

19367 the behavior is undefined. 

19368 RETURN VALUE 

19369 The isdigit () function shall return non-zero if c is a decimal digit; otherwise, it shall return 0. 

19370 ERRORS 

19371 No errors are defined. 

19372 EXAMPLES 

19373 None. 

19374 APPLICATION USAGE 

19375 To ensure applications portability, especially across natural languages, only this function and 

19376 those listed in the SEE ALSO section should be used for character classification. 

19377 RATIONALE 

19378 None. 

19379 FUTURE DIRECTIONS 

19380 None. 

19381 SEE ALSO 

19382 isalnumOf isalpha (), iscntrl() , isgraphO , islowerO, isprintQ, ispunctO , isspaceO, isnpperO, 

19383 isxdigitO, the System Interface Definitions volume of IEEE Std. 1003.1-200x, <ctype.h> 

19384 CHANGE HISTORY 

19385 First released in Issue 1. 

19386 Derived from Issue 1 of the SVID. 

19387 Issue 4 

19388 The text of the DESCRIPTION is revised, although there are no functional differences between 

19389 this issue and Issue 3. 

19390 Issue 6 

19391 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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19392 NAME 

19393 isfdtype — determine whether a file descriptor refers to a socket 

19394 SYNOPSIS 

19395 tinclude <sys/stat.h> 

19396 int isfdtype (int fildes, int fdtype) ; 

19397 DESCRIPTION 

19398 The isfdtype () function shall determine whether the descriptor fildes has the properties identified 

19399 by the value of fdtype, returning 1 if so, and 0 if not. 

19400 If fdtype has the value S_IFSOCK: 

19401 • The isfdtype () function shall return 1 if the descriptor refers to a socket. 

19402 • It is implementation-dependent whether isfdtype () shall return 1 if the descriptor refers to a 

19403 pipe. 

19404 • The function shall return 0 for descriptors that refer neither to a socket nor to a pipe. 

19405 RETURN VALUE 

19406 Upon successful completion, the isfdtype () function shall return a value of 1 or 0 indicating 

19407 whether the descriptor is of the indicated type. Otherwise, it shall return a value of -1 and set 

19408 errno to indicate the error. 

19409 ERRORS 

19410 If any of the following conditions occur, the isfdtype () function shall return -1 and set errno to 

19411 the corresponding value: 

19412 [EBADF] The fildes argument is not a valid file descriptor. 

19413 EXAMPLES 

19414 None. 

19415 APPLICATION USAGE 

19416 None. 

19417 RATIONALE 

19418 None. 

19419 FUTURE DIRECTIONS 

19420 None. 

19421 SEE ALSO 

19422 isatty (), socket(), stat(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

19423 <sys/stat.h> 

19424 CHANGE HISTORY 

19425 Derived from IEEE Std. 1003.1g-2000. 
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19426 NAME 

19427 isgraph — test for a visible character 

19428 SYNOPSIS 

19429 tinclude <ctype.h> 

19430 int isgraph (int c) ; 

19431 DESCRIPTION 

19432 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19433 conflict between the requirements described here and the ISO C standard is unintentional. This I 

19434 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

19435 The isgraph () function shall test whether c is a character of class graph in the program's current I 

19436 locale; see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

19437 In all cases c is an int, the value of which the application shall ensure is a character representable I 

19438 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, I 

19439 the behavior is undefined. 

19440 RETURN VALUE 

19441 The isgraph () function shall return non-zero if c is a character with a visible representation; 

19442 otherwise, it shall return 0. 

19443 ERRORS 

19444 No errors are defined. 

19445 EXAMPLES 

19446 None. 

19447 APPLICATION USAGE 

19448 To ensure applications portability, especially across natural languages, only this function and 

19449 those listed in the SEE ALSO section should be used for character classification. 

19450 RATIONALE 

19451 None. 

19452 FUTURE DIRECTIONS 

19453 None. 

19454 SEE ALSO 

19455 isalnum (), isalpha(), iscntrl(), isdigit( ), islower( ), isprint( ), ispunct( ), isspace( ), isnpper{ ), isxdigit (), 

19456 setlocale(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <ctype.h>, the I 

19457 System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale I 

19458 CHANGE HISTORY 

19459 First released in Issue 1. 

19460 Derived from Issue 1 of the SVID. 

19461 Issue 4 

19462 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 

19463 functional differences between this issue and Issue 3. Operation in the C locale is no longer 

19464 described explicitly on this reference page. I 

19465 Issue 6 I 

19466 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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19467 

19468 

19469 

19470 

19471 

19472 

19473 

19474 

19475 

19476 

19477 

19478 

19479 

19480 

19481 

19482 

19483 

19484 

19485 

19486 

19487 

19488 

19489 

19490 

19491 

19492 

19493 

19494 

19495 

19496 

19497 

19498 

19499 

19500 

19501 

19502 

19503 

19504 

19505 

19506 

19507 

19508 

19509 


NAME 

islower — test for a lowercase letter 

SYNOPSIS 

#include <ctype.h> 
int islower(int c) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 

The islozver () function shall test whether c is a character of class lower in the program's current 
locale; see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. 

In all cases c is an int, the value of which the application shall ensure is a character representable 
as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, 
the behavior is undefined. 

RETURN VALUE 

The islower () function shall return non-zero if c is a lowercase letter; otherwise, it shall return 0. 

ERRORS 

No errors are defined. 

EXAMPLES 

Testing for a Lowercase Letter 

The following example tests whether the value is a lowercase letter, based on the locale of the 
user, then uses it as part of a key value. 

#include <ctype.h> 

#include <stdlib.h> 

#include <locale.h> 

char *keystr; 

int elementlen, len; 

char c; 

setlocale (LC_ALL, 
len = 0; 

while (len < elementlen) { 


c = (char) 

(rand 

if (islower 

(c) ) 


keystr[len++] = c; 

} 


APPLICATION USAGE 

To ensure applications portability, especially across natural languages, only this function and 
those listed in the SEE ALSO section should be used for character classification. 
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19510 RATIONALE 

19511 None. 

19512 FUTURE DIRECTIONS 

19513 None. 

19514 SEE ALSO 

19515 isalnum(), isalplm(), iscntrl(), isdigit (), isgraph(), isprint(), ispnnct{), isspace(), isnpper(), 

19516 isxdigit (), setlocale(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

19517 <ctype.h>, the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale 

19518 CHANGE HISTORY 

19519 First released in Issue 1. 

19520 Derived from Issue 1 of the SVID. 

19521 Issue 4 

19522 

19523 

19524 

19525 Issue 6 

19526 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 


The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 
functional differences between this issue and Issue 3. Operation in the C locale is no longer 
described explicitly on this reference page. 
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19527 NAME 

19528 isnan — test for a NaN 

19529 SYNOPSIS 

19530 xsi tinclude <math.h> 

19531 int isnan (double x) ; 

19532 


19533 DESCRIPTION 

19534 The isnan () function shall test whether x is NaN. 

19535 On systems not supporting NaN values, isnan () shall always return 0. 

19536 RETURN VALUE 

19537 The isnan () function shall return non-zero if x is NaN; otherwise, 0 shall be returned. 


19538 ERRORS 

19539 No errors are defined. 


19540 EXAMPLES 

19541 None. 

19542 APPLICATION USAGE 

19543 None. 

19544 RATIONALE 

19545 None. 

19546 FUTURE DIRECTIONS 

19547 None. 

19548 SEE ALSO 

19549 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

19550 CHANGE HISTORY 

19551 First released in Issue 3. 


19552 Issue 4 

19553 The words "not supporting NaN" are added to the APPLICATION USAGE section. 

19554 Issue 5 

19555 The DESCRIPTION is updated to indicate the return value when NaN is not supported. This 

19556 text was previously published in the APPLICATION USAGE section. 
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19557 NAME 

19558 isprint — test for a printing character 

19559 SYNOPSIS 

19560 tinclude <ctype.h> 

19561 int isprint (int c) ; 

19562 DESCRIPTION 

19563 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19564 conflict between the requirements described here and the ISO C standard is unintentional. This 

19565 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 

19566 The isprint () function shall test whether c is a character of class print in the program's current 

19567 locale; see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. 

19568 In all cases c is an int, the value of which the application shall ensure is a character representable 

19569 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, 

19570 the behavior is undefined. 

19571 RETURN VALUE 

19572 The isprint() function shall return non-zero if c is a printing character; otherwise, it shall return 0. 

19573 ERRORS 

19574 No errors are defined. 

19575 EXAMPLES 

19576 None. 

19577 APPLICATION USAGE 

19578 To ensure applications portability, especially across natural languages, only this function and 

19579 those listed in the SEE ALSO section should be used for character classification. 

19580 RATIONALE 

19581 None. 

19582 FUTURE DIRECTIONS 

19583 None. 

19584 SEE ALSO 

19585 isalnum(), isalplm(), iscntrl(), isdigit (), isgraph(), islower(), ispnnct{), isspace(), isnpper{), 

19586 isxdigit (), setlocale(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

19587 <ctype.h>, the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale 

19588 CHANGE HISTORY 

19589 First released in Issue 1. 

19590 Derived from Issue 1 of the SVID. 

19591 Issue 4 

19592 

19593 

19594 

19595 Issue 6 

19596 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 


The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 
functional differences between this issue and Issue 3. Operation in the C locale is no longer 
described explicitly on this reference page. 
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19597 NAME 

19598 ispunct — test for a punctuation character 

19599 SYNOPSIS 

19600 tinclude <ctype.h> 

19601 int ispunct (int c) ; 

19602 DESCRIPTION 

19603 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19604 conflict between the requirements described here and the ISO C standard is unintentional. This I 

19605 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

19606 The ispunct () function shall test whether c is a character of class punct in the program's current I 

19607 locale; see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

19608 In all cases c is an int, the value of which the application shall ensure is a character representable I 

19609 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, I 

19610 the behavior is undefined. I 

19611 RETURN VALUE 

19612 The ispunct() function shall return non-zero if c is a punctuation character; otherwise, it shall 

19613 return 0. 

19614 ERRORS 

19615 No errors are defined. 

19616 EXAMPLES 

19617 None. 

19618 APPLICATION USAGE 

19619 To ensure applications portability, especially across natural languages, only this function and 

19620 those listed in the SEE ALSO section should be used for character classification. 

19621 RATIONALE 

19622 None. 

19623 FUTURE DIRECTIONS 

19624 None. 

19625 SEE ALSO 

19626 isalnumO , isalpha() , iscntrl() , isdigit ( ), isgraphO , islowerO, isprintQ, isspaceO, isupper(), isxdigitO, 

19627 setlocaleO, the System Interface Definitions volume of IEEE Std. 1003.l-200x, <ctype.h>, the I 

19628 System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale I 

19629 CHANGE HISTORY 

19630 First released in Issue 1. 

19631 Derived from Issue 1 of the SVID. 

19632 Issue 4 

19633 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 

19634 functional differences between this issue and Issue 3. Operation in the C locale is no longer 

19635 described explicitly on this reference page. I 

19636 Issue 6 I 

19637 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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19638 NAME 

19639 isspace — test for a white-space character 

19640 SYNOPSIS 

19641 #include <ctype.h> 

19642 int isspace (int c) ; 

19643 DESCRIPTION 

19644 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19645 conflict between the requirements described here and the ISO C standard is unintentional. This 

19646 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 

19647 The isspace( ) function shall test whether c is a character of class space in the program's current 

19648 locale; see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. 

19649 In all cases c is an int, the value of which the application shall ensure is a character representable 

19650 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, 

19651 the behavior is undefined. 

19652 RETURN VALUE 

19653 The isspace() function shall return non-zero if c is a white-space character; otherwise, it shall 

19654 return 0. 

19655 ERRORS 

19656 No errors are defined. 

19657 EXAMPLES 

19658 None. 

19659 APPLICATION USAGE 

19660 To ensure applications portability, especially across natural languages, only this function and 

19661 those listed in the SEE ALSO section should be used for character classification. 

19662 RATIONALE 

19663 None. 

19664 FUTURE DIRECTIONS 

19665 None. 

19666 SEE ALSO 

19667 isalnum (), isalphaO, iscntrl(), isdigit (), isgraph (), islowerO, isprint() , ispiinct( ), isnpperO, 

19668 isxdigit (), setlocale (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

19669 <ctype.h>, the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale 

19670 CHANGE HISTORY 

19671 First released in Issue 1. 

19672 Derived from Issue 1 of the SVID. 

19673 Issue 4 

19674 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 

19675 functional differences between this issue and Issue 3. Operation in the C locale is no longer 

19676 described explicitly on this reference page. 

19677 Issue 6 

19678 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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19679 NAME 

19680 isupper — test for an uppercase letter 

19681 SYNOPSIS 

19682 #include <ctype.h> 

19683 int isupper (int c) ; 

19684 DESCRIPTION 

19685 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19686 conflict between the requirements described here and the ISO C standard is unintentional. This I 

19687 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

19688 The isupper ( ) function shall test whether c is a character of class upper in the program's current I 

19689 locale; see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

19690 In all cases c is an int, the value of which the application shall ensure is a character representable I 

19691 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, I 

19692 the behavior is undefined. I 

19693 RETURN VALUE 

19694 The isupper( ) function shall return non-zero if c is an uppercase letter; otherwise, it shall return 0. 

19695 ERRORS 

19696 No errors are defined. 

19697 EXAMPLES 

19698 None. 

19699 APPLICATION USAGE 

19700 To ensure applications portability, especially across natural languages, only this function and 

19701 those listed in the SEE ALSO section should be used for character classification. 

19702 RATIONALE 

19703 None. 

19704 FUTURE DIRECTIONS 

19705 None. 

19706 SEE ALSO 

19707 isalnum(), isalplm(), iscntrl(), isdigit (), isgraph(), isloiver(), isprint(), ispunct(), isspace(), isxdigit ( ), 

19708 setlocale(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <ctype.h>, the I 

19709 System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale I 

19710 CHANGE HISTORY 

19711 First released in Issue 1. 

19712 Derived from Issue 1 of the SVID. 

19713 Issue 4 

19714 The text of the DESCRIPTION and RETURN VALUE sections is revised, although there are no 

19715 functional differences between this issue and Issue 3. Operation in the C locale is no longer 

19716 described explicitly on this reference page. I 

19717 Issue 6 I 

19718 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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19719 NAME 

19720 iswalnum — test for an alphanumeric wide-character code 

19721 SYNOPSIS 

19722 #include <wctype.h> 

19723 int iswalnum (wint_t wc) ; 

19724 DESCRIPTION 

19725 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19726 conflict between the requirements described here and the ISO C standard is unintentional. This I 

19727 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

19728 The iswalnum() function shall test whether wc is a wide-character code representing a character 

19729 of class alpha or digit in the program's current locale; see the System Interface Definitions I 

19730 volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

19731 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character I 

19732 code corresponding to a valid character in the current locale, or equal to the value of the macro I 

19733 WEOF. If the argument has any other value, the behavior is undefined. I 

19734 RETURN VALUE 

19735 The iswalnum() function shall return non-zero if wc is an alphanumeric wide-character code; 

19736 otherwise, it shall return 0. 

19737 ERRORS 

19738 No errors are defined. 

19739 EXAMPLES 

19740 None. 

19741 APPLICATION USAGE 

19742 To ensure applications portability, especially across natural languages, only this function and 

19743 those listed in the SEE ALSO section should be used for classification of wide-character codes. 

19744 RATIONALE 

19745 None. 

19746 FUTURE DIRECTIONS 

19747 None. 

19748 SEE ALSO 

19749 iszvalplw(), isivcntrl(), iszvctype(), iswdigit(), isivgraph(), iswlower(), iszvprint(), iswpunct{), 

19750 iszvspace{), iszvupper (), iswxdigit(), setlocale(), the System Interface Definitions volume of 

19751 IEEE Std. 1003.1-200x, <wctype.h>, <wchar.h>, <stdio.h>, the System Interface Definitions I 

19752 volume of IEEE Std. 1003.1-200x, Chapter 7, Locale I 

19753 CHANGE HISTORY 

19754 First released as a World-wide Portability Interface in Issue 4. 

19755 Issue 5 

19756 The following change has been made in this issue for alignment with 

19757 ISO/IEC 9899:1990/Amendment 1:1995 (E): 

19758 • The SYNOPSIS has been changed to indicate that this function and associated data types are 

19759 now made visible by inclusion of the <wctype.h> header rather than <wchar.h>. 
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19760 Issue 6 

19761 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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19762 NAME 

19763 iswalpha — test for an alphabetic wide-character code 

19764 SYNOPSIS 

19765 tinclude <wctype.h> 

19766 int iswalpha (wint_t wc) ; 

19767 DESCRIPTION 

19768 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19769 conflict between the requirements described here and the ISO C standard is unintentional. This I 

19770 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

19771 The isivalpha () function shall test whether zvc is a wide-character code representing a character of 

19772 class alpha in the program's current locale; see the System Interface Definitions volume of I 

19773 IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

19774 In all cases zvc is a wint_t, the value of which the application shall ensure is a wide-character I 

19775 code corresponding to a valid character in the current locale, or equal to the value of the macro I 

19776 WEOF. If the argument has any other value, the behavior is undefined. I 

19777 RETURN VALUE 

19778 The iszvalplm() function shall return non-zero if zvc is an alphabetic wide-character code; 

19779 otherwise, it shall return 0. 

19780 ERRORS 

19781 No errors are defined. 

19782 EXAMPLES 

19783 None. 

19784 APPLICATION USAGE 

19785 To ensure applications portability, especially across natural languages, only this function and 

19786 those listed in the SEE ALSO section should be used for classification of wide-character codes. 

19787 RATIONALE 

19788 None. 

19789 FUTURE DIRECTIONS 

19790 None. 

19791 SEE ALSO 

19792 iszvalnum(), iszvcntrl(), iszvctype(), iszvdigit(), iszvgraph(), iszvlozver(), iszvprint(), iszjvpunct{), 

19793 iszvspace(), iszvupper( ), iszvxdigit (), setlocale(), the System Interface Definitions volume of 

19794 IEEE Std. 1003.1-200x, <wctype.h>, <wchar.h>, <stdio.h>, the System Interface Definitions I 

19795 volume of IEEE Std. 1003.1-200x, Chapter 7, Locale I 

19796 CHANGE HISTORY 

19797 First released in Issue 4. 

19798 Issue 5 

19799 The following change has been made in this issue for alignment with 

19800 ISO/IEC 9899:1990/Amendment 1:1995 (E): 

19801 • The SYNOPSIS has been changed to indicate that this function and associated data types are 

19802 now made visible by inclusion of the <wctype.h> header rather than <wchar.h>. 
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19803 Issue 6 

19804 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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19805 NAME 

19806 iswcntrl — test for a control wide-character code 

19807 SYNOPSIS 

19808 tinclude <wctype.h> 

19809 int iswcntrl (wint_t wc) ; 

19810 DESCRIPTION 

19811 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19812 conflict between the requirements described here and the ISO C standard is unintentional. This I 

19813 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

19814 The iswcntrl () function shall test whether zvc is a wide-character code representing a character of 

19815 class control in the program's current locale; see the System Interface Definitions volume of I 

19816 IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

19817 In all cases zvc is a wint_t, the value of which the application shall ensure is a wide-character I 

19818 code corresponding to a valid character in the current locale, or equal to the value of the macro I 

19819 WEOF. If the argument has any other value, the behavior is undefined. I 

19820 RETURN VALUE 

19821 The iszvcntrl() function shall return non-zero if zvc is a control wide-character code; otherwise, it 

19822 shall return 0. 

19823 ERRORS 

19824 No errors are defined. 

19825 EXAMPLES 

19826 None. 

19827 APPLICATION USAGE 

19828 To ensure applications portability, especially across natural languages, only this function and 

19829 those listed in the SEE ALSO section should be used for classification of wide-character codes. 

19830 RATIONALE 

19831 None. 

19832 FUTURE DIRECTIONS 

19833 None. 

19834 SEE ALSO 

19835 iswalnum(), iszvalpha(), iszvctype(), iswdigit(), iszvgraph(), iswlower(), iswprint( ), iszvpunct(), 

19836 iszvspace(), iszvupper (), iswxdigit(), setlocale(), the System Interface Definitions volume of 

19837 IEEE Std. 1003.1-200x, <wctype.h>, <wchar.h>, the System Interface Definitions volume of I 

19838 IEEE Std. 1003.1-200x, Chapter 7, Locale I 

19839 CHANGE HISTORY 

19840 First released in Issue 4. 

19841 Issue 5 

19842 The following change has been made in this issue for alignment with 

19843 ISO/IEC 9899:1990/Amendment 1:1995 (E): 

19844 • The SYNOPSIS has been changed to indicate that this function and associated data types are 

19845 now made visible by inclusion of the <wctype.h> header rather than <wchar.h>. 
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19846 Issue 6 

19847 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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19848 NAME 

19849 iswctype — test character for a specified class 

19850 SYNOPSIS 

19851 tinclude <wctype.h> 

19852 int iswctype (wint_t wc, wctype_t charclass) ; 

19853 DESCRIPTION 

19854 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19855 conflict between the requirements described here and the ISO C standard is unintentional. This I 

19856 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

19857 The iswctype () function shall determine whether the wide-character code zvc has the character 

19858 class clwrclass, returning true or false. The iswctype () function is defined on WEOF and wide- 

19859 character codes corresponding to the valid character encodings in the current locale. If the zvc 

19860 argument is not in the domain of the function, the result is undefined. If the value of charclass is 

19861 invalid (that is, not obtained by a call to zvctype () or charclass is invalidated by a subsequent call 

19862 to setlocale () that has affected category LC_CTYPE ) the result is implementation-dependent. 

19863 RETURN VALUE 

19864 The iszvctype () function shall return 0 for false and non-zero for true. 

19865 ERRORS 

19866 No errors are defined. 

19867 EXAMPLES 

19868 Testing for a Valid Character 

19869 #include <wctype.h> 

19870 

19871 int yes_or_no; 

19872 wint_t wc; 

19873 wctype_t valid-class; 

19874 

19875 if ( (valid_class=wctype ("upper") ) == (wctype_t)0) 

19876 /* Invalid character class. */ 

19877 yes_or_no=iswctype (wc,valid_class) ; 

19878 APPLICATION USAGE 

19879 The twelve strings "alnum", "alpha", "blank", "cntrl", "digit", "graph", "lower", 

19880 "print", "punct", "space", "upper", and "xdigit" are reserved for the standard 

19881 character classes. In the table below, the functions in the left column are equivalent to the 

19882 functions in the right column. 

19883 iswalnum (wc) iswctype (wc, wctype ( "alnum" ) ) 

19884 iswalpha (wc) iswctype (wc, wctype ( "alpha" ) ) 

19885 iswcntrl (wc) iswctype (wc, wctype (" cntrl ") ) 

19886 iswdigit (wc) iswctype (wc, wctype ( "digit" ) ) 

19887 iswgraph (wc) iswctype (wc, wctype ( "graph" ) ) 

19888 iswlower (wc) iswctype (wc, wctype (" lower") ) 

19889 iswprint (wc) iswctype (wc, wctype ( "print") ) 

19890 iswpunct (wc) iswctype (wc, wctype ( "punct") ) 

19891 iswspace (wc) iswctype (wc, wctype ("space") ) 

19892 iswupper (wc) iswctype (wc, wctype ( "upper") ) 

19893 iswxdigit (wc) iswctype (wc, wctype ("xdigit") ) 
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19894 Note: The call: 

19895 iswctype(wc, wctype ( "blank" ) ) 

19896 does not have an equivalent iszv*( ) function. 

19897 RATIONALE 

19898 None. 

19899 FUTURE DIRECTIONS 

19900 None. 

19901 SEE ALSO 

19902 isivalnnm(), isivalpha(), iswcntrl(), isivdigit(), iszvgraph(), iszvlozver(), iszvprint(), iszvpnnct(), 

19903 iszvspace{), iszvupper(), isivxdigit (), setlocale(), zvctype(), the System Interface Definitions volume 

19904 of IEEE Std. 1003.1-200x, <wctype.h>, <wchar.h> 

19905 CHANGE HISTORY 

19906 First released as World-wide Portability Interfaces in Issue 4. 

19907 Issue 5 

19908 The following change has been made in this issue for alignment with 

19909 ISO/IEC 9899:1990/Amendment 1:1995 (E): 

19910 • The SYNOPSIS has been changed to indicate that this function and associated data types are 

19911 now made visible by inclusion of the <wctype.h> header rather than <wchar.h>. 
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19912 NAME 

19913 iswdigit — test for a decimal digit wide-character code 

19914 SYNOPSIS 

19915 tinclude <wctype.h> 

19916 int iswdigit (wint_t wc) ; 

19917 DESCRIPTION 

19918 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19919 conflict between the requirements described here and the ISO C standard is unintentional. This I 

19920 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

19921 The iswdigit () function shall test whether wc is a wide-character code representing a character of 

19922 class digit in the program's current locale; see the System Interface Definitions volume of I 

19923 IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

19924 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character I 

19925 code corresponding to a valid character in the current locale, or equal to the value of the macro I 

19926 WEOF. If the argument has any other value, the behavior is undefined. I 

19927 RETURN VALUE 

19928 The iswdigit () function shall return non-zero if wc is a decimal digit wide-character code; 

19929 otherwise, it shall return 0. 

19930 ERRORS 

19931 No errors are defined. 

19932 EXAMPLES 

19933 None. 

19934 APPLICATION USAGE 

19935 To ensure applications portability, especially across natural languages, only this function and 

19936 those listed in the SEE ALSO section should be used for classification of wide-character codes. 

19937 RATIONALE 

19938 None. 

19939 FUTURE DIRECTIONS 

19940 None. 

19941 SEE ALSO 

19942 iswalnum(), iszvalpha(), iswcntrl(), iszvctype(), iszvgraph(), iswlower(), iszvprint(), iszvpunct(), 

19943 iszvspace(), iswupper (), iswxdigit(), setlocale(), the System Interface Definitions volume of 

19944 IEEE Std. 1003.1-200x, <wctype.h>, <wchar.h> 

19945 CHANGE HISTORY 

19946 First released in Issue 4. 

19947 Issue 5 

19948 The following change has been made in this issue for alignment with 

19949 ISO/IEC 9899:1990/Amendment 1:1995 (E): 

19950 • The SYNOPSIS has been changed to indicate that this function and associated data types are 

19951 now made visible by inclusion of the <wctype.h> header rather than <wchar.h>. 

19952 Issue 6 I 

19953 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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19954 NAME 

19955 iswgraph — test for a visible wide-character code 

19956 SYNOPSIS 

19957 #include <wctype.h> 

19958 int iswgraph (wint_t wc) ; 

19959 DESCRIPTION 

19960 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

19961 conflict between the requirements described here and the ISO C standard is unintentional. This I 

19962 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

19963 The iswgraph () function shall test whether wc is a wide-character code representing a character 

19964 of class graph in the program's current locale; see the System Interface Definitions volume of I 

19965 IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

19966 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character I 

19967 code corresponding to a valid character in the current locale, or equal to the value of the macro I 

19968 WEOF. If the argument has any other value, the behavior is undefined. I 

19969 RETURN VALUE 

19970 The iszvgraph() function shall return non-zero if zvc is a wide-character code with a visible 

19971 representation; otherwise, it shall return 0. 

19972 ERRORS 

19973 No errors are defined. 

19974 EXAMPLES 

19975 None. 

19976 APPLICATION USAGE 

19977 To ensure applications portability, especially across natural languages, only this function and 

19978 those listed in the SEE ALSO section should be used for classification of wide-character codes. 

19979 RATIONALE 

19980 None. 

19981 FUTURE DIRECTIONS 

19982 None. 

19983 SEE ALSO 

19984 iswalnum(), iszvalpha(), iszvcntrl(), iswctype(), iszudigit (), iswlower(), iswprint(), iswpunct{), 

19985 iszvspace(), iswupper {), iswxdigit(), setlocale(), the System Interface Definitions volume of 

19986 IEEE Std. 1003.1-200x, <wctype.h>, <wchar.h>, the System Interface Definitions volume of I 

19987 IEEE Std. 1003.1-200x, Chapter 7, Locale I 

19988 CHANGE HISTORY 

19989 First released in Issue 4. 

19990 Issue 5 

19991 The following change has been made in this issue for alignment with 

19992 ISO/IEC 9899:1990/Amendment 1:1995 (E): 

19993 • The SYNOPSIS has been changed to indicate that this function and associated data types are 

19994 now made visible by inclusion of the <wctype.h> header rather than <wchar.h>. 
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19995 Issue 6 

19996 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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19997 NAME 

19998 iswlower — test for a lowercase letter wide-character code 

19999 SYNOPSIS 

20000 #include <wctype.h> 

20001 int iswlower (wint_t wc) ; 

20002 DESCRIPTION 

20003 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

20004 conflict between the requirements described here and the ISO C standard is unintentional. This I 

20005 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

20006 The iswlower () function shall test whether wc is a wide-character code representing a character 

20007 of class lower in the program's current locale; see the System Interface Definitions volume of I 

20008 IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

20009 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character I 

20010 code corresponding to a valid character in the current locale, or equal to the value of the macro I 

20011 WEOF. If the argument has any other value, the behavior is undefined. I 

20012 RETURN VALUE 

20013 The iswlower () function shall return non-zero if wc is a lowercase letter wide-character code; 

20014 otherwise, it shall return 0. 

20015 ERRORS 

20016 No errors are defined. 

20017 EXAMPLES 

20018 None. 

20019 APPLICATION USAGE 

20020 To ensure applications portability, especially across natural languages, only this function and 

20021 those listed in the SEE ALSO section should be used for classification of wide-character codes. 

20022 RATIONALE 

20023 None. 

20024 FUTURE DIRECTIONS 

20025 None. 

20026 SEE ALSO 

20027 iswalnum(), isivalpha(), iszvcntrl(), iszvctype(), isiudigit (), iszvgraph(), iswprint(), iswpunct (), 

20028 iszvspace(), iszvupper(), iswxdigit(), setlocale(), the System Interface Definitions volume of 

20029 IEEE Std. 1003.1-200x, <wctype.h>, <wchar.h>, the System Interface Definitions volume of I 

20030 IEEE Std. 1003.1-200x, Chapter 7, Locale I 

20031 CHANGE HISTORY 

20032 First released in Issue 4. 

20033 Issue 5 

20034 The following change has been made in this issue for alignment with 

20035 ISO/IEC 9899:1990/Amendment 1:1995 (E): 

20036 • The SYNOPSIS has been changed to indicate that this function and associated data types are 

20037 now made visible by inclusion of the <wctype.h> header rather than <wchar.h>. 
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20038 Issue 6 

20039 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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20040 NAME 

20041 iswprint — test for a printing wide-character code 

20042 SYNOPSIS 

20043 #include <wctype.h> 

20044 int iswprint (wint_t wc) ; 

20045 DESCRIPTION 

20046 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

20047 conflict between the requirements described here and the ISO C standard is unintentional. This I 

20048 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

20049 The iszvprint( ) function shall test whether zvc is a wide-character code representing a character of 

20050 class print in the program's current locale; see the System Interface Definitions volume of I 

20051 IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

20052 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character I 

20053 code corresponding to a valid character in the current locale, or equal to the value of the macro I 

20054 WEOF. If the argument has any other value, the behavior is undefined. I 

20055 RETURN VALUE 

20056 The iszvprint( ) function shall return non-zero if zvc is a printing wide-character code; otherwise, it 

20057 shall return 0. 

20058 ERRORS 

20059 No errors are defined. 

20060 EXAMPLES 

20061 None. 

20062 APPLICATION USAGE 

20063 To ensure applications portability, especially across natural languages, only this function and 

20064 those listed in the SEE ALSO section should be used for classification of wide-character codes. 

20065 RATIONALE 

20066 None. 

20067 FUTURE DIRECTIONS 

20068 None. 

20069 SEE ALSO 

20070 iswalnum(), iszvalphaO, iswcntrl(), iszvctype(), iswdigit(), iszvgrapli(), iswlower(), iszvpunct(), 

20071 iszvspace(), iszvupper {), iswxdigit(), setlocale(), the System Interface Definitions volume of 

20072 IEEE Std. 1003.1-200x, <wctype.h>, <wchar.h>, the System Interface Definitions volume of I 

20073 IEEE Std. 1003.1-200x, Chapter 7, Locale I 

20074 CHANGE HISTORY 

20075 First released in Issue 4. 

20076 Issue 5 

20077 The following change has been made in this issue for alignment with 

20078 ISO/IEC 9899:1990/Amendment 1:1995 (E): 

20079 • The SYNOPSIS has been changed to indicate that this function and associated data types are 

20080 now made visible by inclusion of the <wctype.h> header rather than <wchar.h>. 
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20081 Issue 6 

20082 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 


System Interfaces, Issue 6 


635 



iswpunct() 


System Interfaces 


20083 NAME 

20084 iswpunct — test for a punctuation wide-character code 

20085 SYNOPSIS 

20086 #include <wctype.h> 

20087 int iswpunct (wint_t wc) ; 

20088 DESCRIPTION 

20089 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

20090 conflict between the requirements described here and the ISO C standard is unintentional. This I 

20091 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

20092 The iswpunct () function shall test whether wc is a wide-character code representing a character 

20093 of class punct in the program's current locale; see the System Interface Definitions volume of I 

20094 IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

20095 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character I 

20096 code corresponding to a valid character in the current locale, or equal to the value of the macro I 

20097 WEOF. If the argument has any other value, the behavior is undefined. I 

20098 RETURN VALUE 

20099 The iszvpunct() function shall return non-zero if zvc is a punctuation wide-character code; 

20100 otherwise, it shall return 0. 

20101 ERRORS 

20102 No errors are defined. 

20103 EXAMPLES 

20104 None. 

20105 APPLICATION USAGE 

20106 To ensure applications portability, especially across natural languages, only this function and 

20107 those listed in the SEE ALSO section should be used for classification of wide-character codes. 

20108 RATIONALE 

20109 None. 

20110 FUTURE DIRECTIONS 

20111 None. 

20112 SEE ALSO 

20113 iswalnum(), iszvalplm(), iszvcntrl(), iswctype(), isiudigit (), iszvgraph(), iszvlozver(), isiuprint (), 

20114 iszvspace(), iszvupper {), iswxdigit(), setlocale(), the System Interface Definitions volume of 

20115 IEEE Std. 1003.1-200x, <wctype.h>, <wchar.h>, the System Interface Definitions volume of I 

20116 IEEE Std. 1003.1-200x, Chapter 7, Locale I 

20117 CHANGE HISTORY 

20118 First released in Issue 4. 

20119 Issue 5 

20120 The following change has been made in this issue for alignment with 

20121 ISO/IEC 9899:1990/Amendment 1:1995 (E): 

20122 • The SYNOPSIS has been changed to indicate that this function and associated data types are 

20123 now made visible by inclusion of the <wctype.h> header rather than <wchar.h>. 
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20124 Issue 6 

20125 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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20126 NAME 

20127 iswspace — test for a white-space wide-character code 

20128 SYNOPSIS 

20129 #include <wctype.h> 

20130 int iswspace (wint_t wc) ; 

20131 DESCRIPTION 

20132 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

20133 conflict between the requirements described here and the ISO C standard is unintentional. This I 

20134 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

20135 The iszvspace( ) function shall test whether wc is a wide-character code representing a character of 

20136 class space in the program's current locale; see the System Interface Definitions volume of I 

20137 IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

20138 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character I 

20139 code corresponding to a valid character in the current locale, or equal to the value of the macro I 

20140 WEOF. If the argument has any other value, the behavior is undefined. I 

20141 RETURN VALUE 

20142 The iszvspace() function shall return non-zero if zvc is a white-space wide-character code; 

20143 otherwise, it shall return 0. 

20144 ERRORS 

20145 No errors are defined. 

20146 EXAMPLES 

20147 None. 

20148 APPLICATION USAGE 

20149 To ensure applications portability, especially across natural languages, only this function and 

20150 those listed in the SEE ALSO section should be used for classification of wide-character codes. 

20151 RATIONALE 

20152 None. 

20153 FUTURE DIRECTIONS 

20154 None. 

20155 SEE ALSO 

20156 iswalnum(), iszvalplm(), iswcntrl(), iswctype(), iswdigit(), iszvgraph(), iszvlozver(), iszvprint(), 

20157 iszvpunct(), iswupper(), iswxdigit(), setlocale(), the System Interface Definitions volume of 

20158 IEEE Std. 1003.1-200x, <wctype.h>, <wchar.h>, the System Interface Definitions volume of I 

20159 IEEE Std. 1003.1-200x, Chapter 7, Locale I 

20160 CHANGE HISTORY 

20161 First released in Issue 4. 

20162 Issue 5 

20163 The following change has been made in this issue for alignment with 

20164 ISO/IEC 9899:1990/Amendment 1:1995 (E): 

20165 • The SYNOPSIS has been changed to indicate that this function and associated data types are 

20166 now made visible by inclusion of the <wctype.h> header rather than <wchar.h>. 
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20167 Issue 6 

20168 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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20169 NAME 

20170 iswupper — test for an uppercase letter wide-character code 

20171 SYNOPSIS 

20172 #include <wctype.h> 

20173 int iswupper (wint_t wc) ; 

20174 DESCRIPTION 

20175 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

20176 conflict between the requirements described here and the ISO C standard is unintentional. This I 

20177 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

20178 The iswupper( ) function shall test whether wc is a wide-character code representing a character 

20179 of class upper in the program's current locale; see the System Interface Definitions volume of I 

20180 IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

20181 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character I 

20182 code corresponding to a valid character in the current locale, or equal to the value of the macro I 

20183 WEOF. If the argument has any other value, the behavior is undefined. I 

20184 RETURN VALUE 

20185 The iswupper( ) function shall return non-zero if zvc is an uppercase letter wide-character code; 

20186 otherwise, it shall return 0. 

20187 ERRORS 

20188 No errors are defined. 

20189 EXAMPLES 

20190 None. 

20191 APPLICATION USAGE 

20192 To ensure applications portability, especially across natural languages, only this function and 

20193 those listed in the SEE ALSO section should be used for classification of wide-character codes. 

20194 RATIONALE 

20195 None. 

20196 FUTURE DIRECTIONS 

20197 None. 

20198 SEE ALSO 

20199 iswalnum(), iszvalphaO, isivcntrl(), iswctype{), isiudigit (), iszvgraph(), iszvlozver(), isivprinti ), 

20200 iszvpunct(), iszvspace(), iszuxdigit (), setlocale(), the System Interface Definitions volume of 

20201 IEEE Std. 1003.1-200x, <wctype.h>, <wchar.h>, the System Interface Definitions volume of I 

20202 IEEE Std. 1003.1-200x, Chapter 7, Locale I 

20203 CHANGE HISTORY 

20204 First released in Issue 4. 

20205 Issue 5 

20206 The following change has been made in this issue for alignment with 

20207 ISO/IEC 9899:1990/Amendment 1:1995 (E): 

20208 • The SYNOPSIS has been changed to indicate that this function and associated data types are 

20209 now made visible by inclusion of the <wctype.h> header rather than <wchar.h>. 
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20210 Issue 6 

20211 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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20212 NAME 

20213 iswxdigit — test for a hexadecimal digit wide-character code 

20214 SYNOPSIS 

20215 #include <wctype.h> 

20216 int iswxdigit (wint_t wc) ; 

20217 DESCRIPTION 

20218 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

20219 conflict between the requirements described here and the ISO C standard is unintentional. This I 

20220 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

20221 The iswxdigit () function shall test whether zvc is a wide-character code representing a character 

20222 of class xdigit in the program's current locale; see the System Interface Definitions volume of I 

20223 IEEE Std. 1003.1-200x, Chapter 7, Locale. I 

20224 In all cases wc is a wint_t, the value of which the application shall ensure is a wide-character I 

20225 code corresponding to a valid character in the current locale, or equal to the value of the macro I 

20226 WEOF. If the argument has any other value, the behavior is undefined. I 

20227 RETURN VALUE 

20228 The iswxdigit () function shall return non-zero if zvc is a hexadecimal digit wide-character code; 

20229 otherwise, it shall return 0. 

20230 ERRORS 

20231 No errors are defined. 

20232 EXAMPLES 

20233 None. 

20234 APPLICATION USAGE 

20235 To ensure applications portability, especially across natural languages, only this function and 

20236 those listed in the SEE ALSO section should be used for classification of wide-character codes. 

20237 RATIONALE 

20238 None. 

20239 FUTURE DIRECTIONS 

20240 None. 

20241 SEE ALSO 

20242 iswalnum(), iszvalphaO, iswcntrl(), iswctype(), iswdigit(), iszvgraph(), iszvlozver(), iszvprint(), 

20243 iszvpunct(), iszvspace(), iswupper (), setlocale(), the System Interface Definitions volume of 

20244 IEEE Std. 1003.1-200x, <wctype.h>, <wchar.h> 

20245 CHANGE HISTORY 

20246 First released in Issue 4. 

20247 Issue 5 

20248 The following change has been made in this issue for alignment with 

20249 ISO/IEC 9899:1990/Amendment 1:1995 (E): 

20250 • The SYNOPSIS has been changed to indicate that this function and associated data types are 

20251 now made visible by inclusion of the <wctype.h> header rather than <wchar.h>. 

20252 Issue 6 I 

20253 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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20254 NAME 

20255 isxdigit — test for a hexadecimal digit 

20256 SYNOPSIS 

20257 #include <ctype.h> 

20258 int isxdigit (int c) ; 

20259 DESCRIPTION 

20260 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

20261 conflict between the requirements described here and the ISO C standard is unintentional. This 

20262 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 

20263 The isxdigit () function shall test whether c is a character of class xdigit in the program's current 

20264 locale; see the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale. 

20265 In all cases c is an int, the value of which the application shall ensure is a character representable 

20266 as an unsigned char or equal to the value of the macro EOF. If the argument has any other value, 

20267 the behavior is undefined. 

20268 RETURN VALUE 

20269 The isxdigit () function shall return non-zero if c is a hexadecimal digit; otherwise, it shall return 

20270 0. 

20271 ERRORS 

20272 No errors are defined. 

20273 EXAMPLES 

20274 None. 

20275 APPLICATION USAGE 

20276 To ensure applications portability, especially across natural languages, only this function and 

20277 those listed in the SEE ALSO section should be used for character classification. 

20278 RATIONALE 

20279 None. 

20280 FUTURE DIRECTIONS 

20281 None. 

20282 SEE ALSO 

20283 isalnum (), isalplm(), iscntrl(), isdigit (), isgraph(), isloiver( ), isprint (), ispnnct (), isspace (), isnpper {), 

20284 the System Interface Definitions volume of IEEE Std. 1003.1-200x, <ctype.h> 

20285 CHANGE HISTORY 

20286 First released in Issue 1. 

20287 Derived from Issue 1 of the SVID. 

20288 Issue 4 

20289 The text of the DESCRIPTION is revised, although there are no functional differences between 

20290 this issue and Issue 3. 

20291 Issue 6 

20292 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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20293 NAME 

20294 jO, jl, jn — Bessel functions of the first kind 

20295 SYNOPSIS 

20296 xsi #include <math.h> 


20297 

double 

jO(double 

x) } 

20298 

double 

j1(double 

x) ; 

20299 

double 

jn(int n, 

double x); 


20300 

20301 DESCRIPTION 

20302 The j0( ), jl (), and jn () functions shall compute Bessel functions of x of the first kind of orders 0, 

20303 1, and n respectively. 

20304 An application wishing to check for error situations should set errno to 0 before calling j0( ), jl ( ), 

20305 or jn (). If errno is non-zero on return, or the return value is NaN, an error has occurred. 

20306 RETURN VALUE 

20307 Upon successful completion, j0 (), jl ( ), and jn ( ) shall return the relevant Bessel value of x of the 

20308 first kind. 

20309 If the x argument is too large in magnitude, 0 shall be returned and errno may be set to 

20310 [ERANGE]. 

20311 If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

20312 If the correct result would cause underflow, 0 shall be returned and errno may be set to 

20313 [ERANGE]. 

20314 ERRORS 

20315 The j0( ), jl (), and jn () functions may fail if: 

20316 [EDOM] The value of x is NaN. 

20317 [ERANGE] The value of x was too large in magnitude, or underflow occurred. 

20318 No other errors shall occur. 

20319 EXAMPLES 

20320 None. 

20321 APPLICATION USAGE 

20322 None. 

20323 RATIONALE 

20324 None. 

20325 FUTURE DIRECTIONS 

20326 None. 

20327 SEE ALSO 

20328 isnan (), y0(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

20329 CHANGE HISTORY 

20330 First released in Issue 1. 

20331 Derived from Issue 1 of the SVID. 


644 


Technical Standard (2000) (Draft February 29, 2000) 




20332 

20333 

20334 

20335 

20336 

20337 

20338 


System Interfaces 


joo 


Issue 4 

References to matherr () are removed. 

The RETURN VALUE and ERRORS sections are substantially rewritten to rationalize error 
handling in the mathematics functions. 


Issue 5 

The DESCRIPTION is updated to indicate how an application should check for an error. This 
text was previously published in the APPLICATION USAGE section. 
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20339 NAME 

20340 jrand48 — generate a uniformly distributed pseudo-random long signed integer 

20341 SYNOPSIS 

20342 xsi #include <stdlib.h> 

20343 long int jrand48 (unsigned short int xsubi[3]); 

20344 

20345 DESCRIPTION 

20346 Refer to drand48 (). 
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20347 

20348 

20349 

20350 

20351 

20352 

20353 

20354 

20355 

20356 

20357 

20358 

20359 

20360 

20361 

20362 

20363 

20364 

20365 

20366 

20367 

20368 

20369 

20370 

20371 

20372 

20373 

20374 

20375 

20376 

20377 

20378 

20379 

20380 

20381 

20382 

20383 

20384 

20385 

20386 

20387 

20388 

20389 


NAME 

kill — send a signal to a process or a group of processes 

SYNOPSIS 

#include <signal.h> 

int kill(pid_t pid, int sig); 

DESCRIPTION 

The kill () function shall send a signal to a process or a group of processes specified by pid . The 
signal to be sent is specified by sig and is either one from the list given in <signal.h> or 0. If sig is 
0 (the null signal), error checking is performed but no signal is actually sent. The null signal can 
be used to check the validity of pid. 

For a process to have permission to send a signal to a process designated by pid, unless the I 
sending process has appropriate privileges, the application shall ensure that the real or effective I 
user ID of the sending process matchs the real or saved set-user-ID of the receiving process. I 

If pid is greater than 0, sig shall be sent to the process whose process ID is equal to pid. 

If pid is 0, sig shall be sent to all processes (excluding an unspecified set of system processes) 
whose process group ID is equal to the process group ID of the sender, and for which the 
process has permission to send a signal. 

man If pid is -1, sig shall be sent to all processes (excluding an unspecified set of system processes) for 
which the process has permission to send that signal. 

If pid is negative, but not -1, sig shall be sent to all processes (excluding an unspecified set of 
system processes) whose process group ID is equal to the absolute value of pid, and for which 
the process has permission to send a signal. 

If the value of pid causes sig to be generated for the sending process, and if sig is not blocked for 
the calling thread and if no other thread has sig unblocked or is waiting in a sigzvait() function 
for sig, either sig or at least one pending unblocked signal shall be delivered to the sending 
thread before kill () returns. 

The user ID tests described above shall not be applied when sending SIGCONT to a process that 
is a member of the same session as the sending process. 

An implementation that provides extended security controls may impose further 
implementation-dependent restrictions on the sending of signals, including the null signal. In 
particular, the system may deny the existence of some or all of the processes specified by pid. 

The kill() function is successful if the process has permission to send sig to any of the processes 
specified by pid . If kill () fails, no signal shall be sent. 

RETURN VALUE 

Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 
indicate the error. 

ERRORS 

The kill () function shall fail if: 

[EINVAL] The value of the sig argument is an invalid or unsupported signal number. 

[EPERM] The process does not have permission to send the signal to any receiving 

process. 

[ESRCH] No process or process group can be found corresponding to that specified by 

pid. 
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20390 EXAMPLES 

20391 None. 

20392 APPLICATION USAGE 

20393 None. 

20394 RATIONALE 

20395 The semantics for permission checking for kill () differed between System V and most other 

20396 implementations, such as Version 7 or 4.3 BSD. The semantics chosen for this volume of 

20397 IEEE Std. 1003.1-200x agree with System V. Specifically, a set-user-ID process cannot protect 

20398 itself against signals (or at least not against SIGKILL) unless it changes its real user ID. This 

20399 choice allows the user who starts an application to send it signals even if it changes its effective 

20400 user ID. The other semantics give more power to an application that wants to protect itself from 

20401 the user who ran it. 

20402 Some implementations provide semantic extensions to the kill() function when the absolute 

20403 value of pid is greater than some maximum, or otherwise special, value. Negative values are a 

20404 flag to kill(). Since most implementations return [ESRCH] in this case, this behavior is not 

20405 included in this volume of IEEE Std. 1003.1-200x, although a conforming implementation could 

20406 provide such an extension. 

20407 The implementation-dependent processes to which a signal cannot be sent may include the 

20408 scheduler or init. 

20409 There was initially strong sentiment to specify that, if pid specifies that a signal be sent to the 

20410 calling process and that signal is not blocked, that signal would be delivered before kill() 

20411 returns. This would permit a process to call kill() and be guaranteed that the call never return. 

20412 However, historical implementations that provide only the signal () function make only the 

20413 weaker guarantee in this volume of IEEE Std. 1003.1-200x, because they only deliver one signal 

20414 each time a process enters the kernel. Modifications to such implementations to support the 

20415 sigaction () function generally require entry to the kernel following return from a signal-catching 

20416 function, in order to restore the signal mask. Such modifications have the effect of satisfying the 

20417 stronger requirement, at least when sigaction () is used, but not necessarily when signal () is used. 

20418 The developers of this volume of IEEE Std. 1003.1-200x considered making the stronger 

20419 requirement except when signal () is used, but felt this would be unnecessarily complex. 

20420 Implementors are encouraged to meet the stronger requirement whenever possible. In practice, 

20421 the weaker requirement is the same, except in the rare case when two signals arrive during a 

20422 very short window. This reasoning also applies to a similar requirement for sigprocmask( ). 

20423 In 4.2 BSD, the SIGCONT signal can be sent to any descendant process regardless of user-ID 

20424 security checks. This allows a job control shell to continue a job even if processes in the job have 

20425 altered their user IDs (as in the sn command). In keeping with the addition of the concept of 

20426 sessions, similar functionality is provided by allowing the SIGCONT signal to be sent to any 

20427 process in the same session regardless of user ID security checks. This is less restrictive than BSD 

20428 in the sense that ancestor processes (in the same session) can now be the recipient. It is more 

20429 restrictive than BSD in the sense that descendant processes that form new sessions are now 

20430 subject to the user ID checks. A similar relaxation of security is not necessary for the other job 

20431 control signals since those signals are typically sent by the terminal driver in recognition of 

20432 special characters being typed; the terminal driver bypasses all security checks. 

20433 In secure implementations, a process may be restricted from sending a signal to a process having 

20434 a different security label. In order to prevent the existence or nonexistence of a process from 

20435 being used as a covert channel, such processes should appear nonexistent to the sender; that is, 

20436 [ESRCH] should be returned, rather than [EPERM], if pid refers only to such processes. 
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20437 

20438 

20439 

20440 

20441 

20442 

20443 

20444 

20445 

20446 

20447 

20448 

20449 

20450 

20451 

20452 

20453 

20454 

20455 

20456 

20457 

20458 

20459 

20460 

20461 

20462 

20463 

20464 

20465 

20466 

20467 

20468 

20469 

20470 

20471 

20472 

20473 

20474 

20475 

20476 

20477 

20478 


Existing implementations vary on the result of a kill () with pid indicating an inactive process (a 
terminated process that has not been waited for by its parent). Some indicate success on such a 
call (subject to permission checking), while others give an error of [ESRCH], Since the definition 
of process lifetime in this volume of IEEE Std. 1003.1-200x covers inactive processes, the 
[ESRCH] error as described is inappropriate in this case. In particular, this means that an 
application cannot have a parent process check for termination of a particular child with kill(). 
(Usually this is done with the null signal; this can be done reliably with ivaitpid ().) 

There is some belief that the name kill() is misleading, since the function is not always intended 
to cause process termination. However, the name is common to all historical implementations, 
and any change would be in conflict with the goal of minimal changes to existing application 
code. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

getpid (), raise(), setsid(), sigaction(), sigquene(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <signal.h>, <sys/types.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

XSI-conformant systems. 

The DESCRIPTION is clarified in various places. 

The following change is incorporated for alignment with the FIPS requirements: 

• In the DESCRIPTION, the second paragraph is reworded to indicate that the saved set-user- 
ID of the calling process is checked in place of its effective user ID. This functionality is 
marked as an extension. 

Issue 5 

The DESCRIPTION is updated for alignment with POSIX Threads Extension. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 

Single UNIX Specification: 

• In the DESCRIPTION, the second paragraph is reworded to indicate that the saved set-user- 
ID of the calling process is checked in place of its effective user ID. This is a FIPS 
requirement. 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• The behavior when pid is -1 is now specified. It was previously explicitly unspecified in the 
POSIX.1-1988 standard. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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20479 NAME 

20480 killpg — send a signal to a process group 

20481 SYNOPSIS 

20482 xsi #include <signal.h> 

20483 int killpg (pid_t pgrp, int sig) ; 

20484 

20485 DESCRIPTION 

20486 The killpg () function shall send the signal specified by sig to the process group specified by pgrp. 

20487 If pgrp is greater than 1, killpg(pgrp, sig) shall be equivalent to kill(-pgrp, sig). If pgrp is less than or 

20488 equal to 1, the behavior of killpg () is undefined. 

20489 RETURN VALUE 

20490 Refer to kill (). 

20491 ERRORS 

20492 Refer to kill (). 

20493 EXAMPLES 

20494 None. 

20495 APPLICATION USAGE 

20496 None. 

20497 RATIONALE 

20498 None. 

20499 FUTURE DIRECTIONS 

20500 None. 

20501 SEE ALSO 

20502 getpgid (), getpid (), kill(), raise (), the System Interface Definitions volume of 

20503 IEEE Std. 1003.1-200x, <signal.h> 

20504 CHANGE HISTORY 

20505 First released in Issue 4, Version 2. 

20506 Issue 5 

20507 Moved from X/OPEN UNIX extension to BASE. 
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20508 NAME 

20509 164a — convert a 32-bit integer to a radix-64 ASCII string 

20510 SYNOPSIS 

20511 xsi tinclude <stdlib.h> 

20512 char *164a(long value); 

20513 

20514 DESCRIPTION 

20515 Refer to a64l(). 
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20516 NAME 

20517 labs — return a long integer absolute value 

20518 SYNOPSIS 

20519 #include <stdlib.h> 

20520 long int labs (long int i); 

20521 DESCRIPTION 

20522 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

20523 conflict between the requirements described here and the ISO C standard is unintentional. This I 

20524 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

20525 The labs () function shall compute the absolute value of its long integer operand, i. If the result 

20526 cannot be represented, the behavior is undefined. 

20527 RETURN VALUE 

20528 The labs () function shall return the absolute value of its long integer operand. 

20529 ERRORS 

20530 No errors are defined. 

20531 EXAMPLES 

20532 None. 

20533 APPLICATION USAGE 

20534 None. 

20535 RATIONALE 

20536 None. 

20537 FUTURE DIRECTIONS 

20538 None. 

20539 SEE ALSO 

20540 abs( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

20541 CHANGE HISTORY 

20542 First released in Issue 4. 

20543 Derived from the ISO C standard. 
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20544 NAME 

20545 lchown — change the owner and group of a symbolic link 

20546 SYNOPSIS 

20547 xsi #include <unistd.h> 

20548 int lchown (const char *path, uid_t owner, gid_t group); 

20549 

20550 DESCRIPTION 

20551 The lchown () function shall have the same effect as chown () except in the case where the named 

20552 file is a symbolic link. In this case, lchown () shall change the ownership of the symbolic link file 

20553 itself, while chown () changes the ownership of the file or directory to which the symbolic link 

20554 refers. 

20555 RETURN VALUE 

20556 Upon successful completion, Ichozvn () shall return 0. Otherwise, it shall return -1 and set errno to 

20557 indicate an error. 

20558 ERRORS 

20559 The lchown () function shall fail if: 

20560 [EACCES] Search permission is denied on a component of the path prefix of path. 

20561 [EINVAL] The owner or group ID is not a value supported by the implementation. 

20562 [ENAMETOOLONG] 

20563 The length of a path name exceeds {PATH_MAX}, or path name component is 

20564 longer than [NAME_MAX[. 

20565 [ENOENT] A component of path does not name an existing file or path is an empty string. 

20566 [ENOTDIR] A component of the path prefix of path is not a directory. 

20567 [EOPNOTSUPP] The path argument names a symbolic link and the implementation does not 

20568 support setting the owner or group of a symbolic link. 

20569 [ELOOP] Too many symbolic links were encountered in resolving path. 

20570 [EPERM] The effective user ID does not match the owner of the file and the process 

20571 does not have appropriate privileges. 

20572 [EROFS] The file resides on a read-only file system. 

20573 The Ichozvn () function may fail if: 

20574 [EIO] An I/O error occurred while reading or writing to the file system. 

20575 [EINTR] A signal was caught during execution of the function. 

20576 [ENAMETOOLONG] 

20577 Path name resolution of a symbolic link produced an intermediate result 

20578 whose length exceeds |PATH_MAX[. 
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20579 EXAMPLES 

20580 Changing the Current Owner of a File 

20581 The following example shows how to change the ownership of the symbolic link named 

20582 /modules/passl to the user ID associated with "jones" and the group ID associated with "end”. 

20583 The numeric value for the user ID is obtained by using the getpzvnam() function. The numeric 

20584 value for the group ID is obtained by using the getgrnam( ) function. 

20585 #include <sys/types . h> 

20586 #include <unistd.h> 

20587 #include <pwd.h> 

20588 #include <grp.h> 

20589 struct passwd *pwd; 

20590 struct group *grp; 

20591 char *path = "/modules/passl"; 

20592 

20593 pwd = getpwnam (" jones ") ; 

20594 grp = getgrnam ( " end" ) ; 

20595 lchown (path, pwd->pw_uid, grp->gr_gid) ; 

20596 APPLICATION USAGE 

20597 None. 

20598 RATIONALE 

20599 None. 

20600 FUTURE DIRECTIONS 

20601 None. 

20602 SEE ALSO 

20603 chozvn (), symlink( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

20604 CHANGE HISTORY 

20605 First released in Issue 4, Version 2. 

20606 Issue 5 

20607 Moved from X/OPEN UNIX extension to BASE. 
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20608 NAME 

20609 lcong48 — seed a uniformly distributed pseudo-random signed long integer generator 

20610 SYNOPSIS 

20611 xsi #include <stdlib.h> 

20612 void lcong4 8 (unsigned short int param[l ]); 

20613 

20614 DESCRIPTION 

20615 Refer to dmnd48 (). 
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20616 

20617 

20618 

20619 

20620 

20621 

20622 

20623 

20624 

20625 

20626 

20627 

20628 

20629 

20630 

20631 

20632 

20633 

20634 

20635 

20636 

20637 

20638 

20639 

20640 

20641 

20642 

20643 

20644 

20645 

20646 

20647 

20648 

20649 

20650 

20651 

20652 

20653 

20654 


NAME 

ldexp — load exponent of a floating point number 

SYNOPSIS 

#include <math.h> 

double ldexp(double x, int exp ); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The ldexp () function shall compute the quantity x * 2 l A/ ’. 

An application wishing to check for error situations should set errno to 0 before calling ldexp (). 

If errno is non-zero on return, or the return value is NaN, an error has occurred. 

RETURN VALUE 

Upon successful completion, ldexp () shall return a double representing the value x multiplied by 
2 raised to the power exp. 

xsi If the value of x is NaN, NaN shall be returned and errno may be set to [EDOM], 

If ldexp() would cause overflow, ±HUGE_VAL shall be returned (according to the sign of x), and 
errno shall be set to [ERANGE]. 

If ldexp () would cause underflow, 0 shall be returned and errno may be set to [ERANGE]. 

ERRORS 

The ldexp () function shall fail if: 

[ERANGE] The value to be returned would have caused overflow. 

The ldexp () function may fail if: 
xsi [EDOM] The argument x is NaN. 

[ERANGE] The value to be returned would have caused underflow. 

No other errors shall occur. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

frexpOr isnan (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 
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20655 

20656 

20657 

20658 

20659 

20660 
20661 
20662 


Issue 4 

References to matherr () are removed. 

The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 
ISO C standard and to rationalize error handling in the mathematics functions. 

The return value specified for [EDOM] is marked as an extension. 


Issue 5 

The DESCRIPTION is updated to indicate how an application should check for an error. This 
text was previously published in the APPLICATION USAGE section. 
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20663 NAME 

20664 ldiv — compute quotient and remainder of a long division 

20665 SYNOPSIS 

20666 tinclude <stdlib.h> 

20667 ldiv_t ldiv (long int numer, long int denom) ; 

20668 DESCRIPTION 

20669 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

20670 conflict between the requirements described here and the ISO C standard is unintentional. This I 

20671 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

20672 The ldiv () function shall compute the quotient and remainder of the division of the numerator 

20673 nnmer by the denominator denom. If the division is inexact, the resulting quotient is the long 

20674 integer of lesser magnitude that is the nearest to the algebraic quotient. If the result cannot be 

20675 represented, the behavior is undefined; otherwise, qnot * denom+rem shall equal nnmer. 

20676 RETURN VALUE 

20677 The ldiv () function shall return a structure of type ldiv_t, comprising both the quotient and the 

20678 remainder. The structure includes the following members, in any order: 

20679 long int quot; /* Quotient */ 

20680 long int rem; /* Remainder */ 

20681 ERRORS 

20682 No errors are defined. 

20683 EXAMPLES 

20684 None. 

20685 APPLICATION USAGE 

20686 None. 

20687 RATIONALE 

20688 None. 

20689 FUTURE DIRECTIONS 

20690 None. 

20691 SEE ALSO 

20692 div( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

20693 CHANGE HISTORY 

20694 First released in Issue 4. 

20695 Derived from the ISO C standard. 
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20696 NAME 

20697 lfind — find entry in a linear search table 

20698 SYNOPSIS 

20699 xsi #include <search.h> 

20700 void *lfind (const void *key, const void *base r size_t *nelp, 

20701 size_t width, int ( *compar ) (const void *, const void *)); 

20702 

20703 DESCRIPTION 

20704 Refer to Isearch ( ). 
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20705 

20706 

20707 

20708 

20709 

20710 

20711 

20712 

20713 

20714 

20715 

20716 

20717 

20718 

20719 

20720 

20721 

20722 

20723 

20724 

20725 

20726 

20727 

20728 

20729 

20730 

20731 

20732 

20733 

20734 

20735 

20736 

20737 

20738 

20739 

20740 

20741 

20742 

20743 

20744 


NAME 

lgamma — log gamma function 

SYNOPSIS 

xsi tinclude <math.h> 

double lgamma(double x); 
extern int signgam; 

DESCRIPTION 

The lgamma() function shall compute log,,|T(x)| where T(x) is defined as j e~ l t x ~ 1 dt. The sign of 

o 

T(x) is returned in the external integer signgam. The argument x need not be a non-positive 
integer (T( x) is defined over the reals, except the non-positive integers). 

An application wishing to check for error situations should set errno to 0 before calling IgammaO- 
If errno is non-zero on return, or the return value is NaN, an error has occurred. 

The IgammaO function need not be reentrant. A function that is not required to be reentrant is 
not required to be thread-safe. 

RETURN VALUE 

Upon successful completion, IgammaO shall return the logarithmic gamma of x. 

If x is NaN, NaN shall be returned and errno may be set to [EDOM]. 

If x is a non-positive integer, either HUGE_VAL or NaN shall be returned and errno may be set to 
[EDOM]. 

If the correct value would cause overflow, lgamma () shall return HUGE_VAL and may set errno 
to [ERANGE], 

If the correct value would cause underflow, IgammaO shall return 0 and may set errno to 
[ERANGE], 

ERRORS 

The lgamma () function may fail if: 

[EDOM] The value of x is a non-positive integer or NaN. 

[ERANGE] The value to be returned would have caused overflow or underflow. 

No other errors shall occur. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

exp (), is nan (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 
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20745 CHANGE HISTORY 

20746 First released in Issue 3. 

20747 Issue 4 

20748 This page no longer points to gamma (), but contains all information relating to Igamma (). 

20749 The RETURN VALUE and ERRORS sections are substantially rewritten to rationalize error 

20750 handling in the mathematics functions. 

20751 Issue 5 

20752 The DESCRIPTION is updated to indicate how an application should check for an error. This 

20753 text was previously published in the APPLICATION USAGE section. 

20754 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 
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20755 NAME 

20756 link — link to a file 

20757 SYNOPSIS 

20758 #include <unistd.h> 

20759 int link (const char *pathl, const char *path2); 

20760 DESCRIPTION 

20761 The link( ) function shall create a new link (directory entry) for the existing file, pathl. 

20762 The pathl argument points to a path name naming an existing file. The path2 argument points to 

20763 a path name naming the new directory entry to be created. The link( ) function shall atomically 

20764 create a new link for the existing file and the link count of the file shall be incremented by one. 

20765 If pathl names a directory, link( ) shall fail unless the process has appropriate privileges and the 

20766 implementation supports using link( ) on directories. 

20767 Upon successful completion, link() shall mark for update the st_ctime field of the file. Also, the 

20768 st_ctime and stjntime fields of the directory that contains the new entry shall be marked for 

20769 update. 

20770 If link( ) fails, no link shall be created and the link count of the file shall remain unchanged. 

20771 The implementation may require that the calling process has permission to access the existing 

20772 file. 

20773 RETURN VALUE 

20774 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 

20775 indicate the error. 

20776 ERRORS 

20777 The link( ) function shall fail if: 


20778 

20779 

20780 

20781 

[EACCES] 

A component of either path prefix denies search permission, or the requested 
link requires writing in a directory that denies write permission, or the calling 
process does not have permission to access the existing file and this is 
required by the implementation. 

20782 

[EEXIST] 

The path2 argument resolves to an existing file or refers to a symbolic link. 

20783 MAN 

20784 

[ELOOP] 

A loop exists in symbolic links encountered during resolution of the path 1 or 
path2 argument. 

20785 

[EMLINK] 

The number of links to the file named by pathl would exceed |LINK_MAX}. 

20786 

20787 

20788 

[ENAMETOOLONG] 

The length of pathl or path! exceeds {PATH_MAX} or a path name component 
is longer than {NAME_MAX} while _POSIX_NO_TRUNC is in effect. 

20789 

20790 

[ENOENT] 

A component of either path prefix does not exist; the file named by pathl does 
not exist; or pathl or path2 points to an empty string. 

20791 

[ENOSPC] 

The directory to contain the link cannot be extended. 

20792 

[ENOTDIR] 

A component of either path prefix is not a directory. 

20793 

20794 

20795 

[EPERM] 

The file named by pathl is a directory and either the calling process does not 
have appropriate privileges or the implementation prohibits using link() on 
directories. 


662 


Technical Standard (2000) (Draft February 29, 2000) 




System Interfaces 


link() 


20796 [EROFS] The requested link requires writing in a directory on a read-only file system. 

20797 [EXDEV] The link named by path2 and the file named by pathl are on different file 

20798 xsr systems and the implementation does not support links between file systems, I 

20799 or pathl refers to a named STREAM. 

20800 The link( ) function may fail if: 

20801 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during I 

20802 resolution of the pathl or path2 argument. I 

20803 man [ENAMETOOLONG] 

20804 As a result of encountering a symbolic link in resolution of the pathl or path2 I 

20805 argument, the length of the substituted path name string exceeded I 

20806 |PATH_MAX}. 

20807 EXAMPLES 

20808 Creating a Link to a File 

20809 The following example shows how to create a link to a file named /home/cnd/modl by creating a 

20810 new directory entry named /modules/passl. 

20811 #include <unistd.h> 


20812 

char 

*pathl = 

"/home/cnd/modl"; 

20813 

char 

*path2 = 

"/modules/passl" 

20814 

int 

status; 


20815 




20816 

status = link 

(pathl, path2); 


20817 Creating a Link to a File Within a Program 

20818 In the following program example, the link() function is used to link the /etc/passwd file 

20819 (defined as PASSWDFILE) to a file named /etc/opasswd (defined as SAVEFILE), which is used 

20820 to save the current password file. Then, after removing the current password file (defined as 

20821 PASSWDFILE), the new password file is saved as the current password file using the link() 

20822 function again. 

20823 #include <unistd.h> 

20824 #define LOCKFILE "/etc/ptmp" 

20825 #define PASSWDFILE "/etc/passwd" 

20826 #define SAVEFILE "/etc/opasswd" 

20827 

20828 /* Save current password file */ 

20829 link (PASSWDFILE, SAVEFILE); 

20830 /* Remove current password file. */ 

20831 unlink (PASSWDFILE); 

20832 /* Save new password file as current password file. */ 

20833 link (LOCKFILE, PASSWDFILE) ; 

20834 APPLICATION USAGE 

20835 Some implementations do allow links between file systems. 
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20836 

20837 

20838 

20839 

20840 

20841 

20842 

20843 

20844 

20845 

20846 

20847 

20848 

20849 

20850 

20851 

20852 

20853 

20854 

20855 

20856 

20857 

20858 

20859 

20860 

20861 

20862 

20863 

20864 

20865 

20866 

20867 

20868 

20869 

20870 

20871 

20872 

20873 

20874 

20875 

20876 


RATIONALE 

Linking to a directory is restricted to the superuser in most historical implementations because 
this capability may produce loops in the file hierarchy or otherwise corrupt the file system. This 
volume of IEEEStd. 1003.1-200x continues that philosophy by prohibiting link() and unlink() 
from doing this. Other functions could do it if the implementor designed such an extension. 

Some historical implementations allow linking of files on different file systems. Wording was 
added to explicitly allow this optional behavior. 

The exception for cross-file system links is intended to apply only to links that are I 
programmatically indistinguishable from "hard" links. I 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

symlink(), unlink(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

<unistd.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The <unistd.h> header is added to the SYNOPSIS section. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The type of arguments pat I Cl and path2 are changed from char* to const char*. 

The following change is incorporated for alignment with the FIPS requirements: 

• In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 
name component is larger that |NAME_MAX[ is now defined as mandatory and marked as 
an extension. 

Issue 4, Version 2 

The ERRORS section is updated for X/OPEN UNIX conformance as follows: 

• The [ELOOP] error is returned if too many symbolic links are encountered during path name 
resolution. 

• The [EXDEV] error may also be returned if pathl refers to a named STREAM. 

• A second [ENAMETOOLONG] condition is defined that may report excessive length of an 
intermediate result of path name resolution of a symbolic link. 

Issue 6 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 
This is since behavior may vary from one file system to another. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The [ELOOP] mandatory error condition is added. 

• A second [ENAMETOOLONG] is added as an optional error condition. 

The following changes were made to align with the IEEE P1003.1a draft standard: 
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• An explanation is added of action when path! refers to a symbolic link. 

• The [ELOOP] optional error condition is added. 
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20879 NAME 

20880 lio listio — list directed I/O (REALTIME) 

20881 SYNOPSIS 

20882 AIO tinclude <aio.h> 

20883 int lio_listio (int mode, struct aiocb * const list[], int nent, 

20884 struct sigevent *sig) ; 

20885 

20886 DESCRIPTION 

20887 The lio_listio() function allows the calling process to initiate a list of I/O requests with a single 

20888 function call. 

20889 The mode argument takes one of the values LIO_WAIT or LIO_NOWAIT declared in <aio.h> and 

20890 determines whether the function returns when the I/O operations have been completed, or as 

20891 soon as the operations have been queued. If the mode argument is LIO_WAIT, the function waits 

20892 until all I/O is complete and the sig argument is ignored. 

20893 If the mode argument is LIO_NOWAIT, the function shall return immediately, and asynchronous 

20894 notification shall occur, according to the sig argument, when all the I/O operations complete. If 

20895 sig is NULL, then no asynchronous notification shall occur. If sig is not NULL, asynchronous 

20896 notification occurs as specified in Section 2.4.1 on page 43 when all the requests in list have 

20897 completed. 

20898 The I/O requests enumerated by list are submitted in an unspecified order. 

20899 The list argument is an array of pointers to aiocb structures. The array contains nent elements. 

20900 The array may contain NULL elements, which shall be ignored. 

20901 The aio_lio_opcode field of each aiocb structure specifies the operation to be performed. The 

20902 supported operations are LIO_READ, LIO_WRITE, and LIO_NOP; these symbols are defined in 

20903 <aio.h>. The LIO_NOP operation causes the list entry to be ignored. If the aio_lio_opcode 

20904 element is equal to LIO_READ, then an I/O operation is submitted as if by a call to aio_read() 

20905 with the aiocbp equal to the address of the aiocb structure. If the aio_lio_opcode element is equal 

20906 to LIO_WRITE, then an I/O operation is submitted as if by a call to aio_write() with the aiocbp 

20907 equal to the address of the aiocb structure. 

20908 The aio^ildes member specifies the file descriptor on which the operation is to be performed. 

20909 The aio_bnf member specifies the address of the buffer to or from which the data is transferred. 

20910 The aio_nbytes member specifies the number of bytes of data to be transferred. 

20911 The members of the aiocb structure further describe the I/O operation to be performed, in a 

20912 manner identical to that of the corresponding aiocb structure when used by the aio_read () and 

20913 aio_write( ) functions. 

20914 The nent argument specifies how many elements are members of the list; that is, the length of the 

20915 array. 

20916 The behavior of this function is altered according to the definitions of synchronized I/O data 

20917 integrity completion and synchronized I/O file integrity completion if synchronized I/O is 

20918 enabled on the file associated with aiojildes. 

20919 man For regular files, no data transfer shall occur past the offset maximum established in the open 

20920 file description associated with aiocbp-^aiojildes. 


666 


Technical Standard (2000) (Draft February 29, 2000) 




System Interfaces 


lio_listio() 


20921 

20922 

20923 

20924 

20925 

20926 

20927 

20928 

20929 

20930 

20931 

20932 

20933 

20934 

20935 

20936 

20937 

20938 

20939 

20940 

20941 

20942 

20943 

20944 

20945 

20946 

20947 

20948 

20949 

20950 

20951 

20952 

20953 

20954 

20955 

20956 

20957 

20958 

20959 

20960 

20961 

20962 

20963 

20964 

20965 

20966 


RETURN VALUE 

If the mode argument has the value LIO_NOWAIT, the liojistio () function shall return the value 
zero if the I/O operations are successfully queued; otherwise, the function shall return the value 
-1 and set errno to indicate the error. 

If the mode argument has the value LIO_WAIT, the liojistio () function shall return the value 
zero when all the indicated I/O has completed successfully. Otherwise, liojistio () shall return a 
value of -1 and set errno to indicate the error. 

In either case, the return value only indicates the success or failure of the liojistio () call itself, 
not the status of the individual I/O requests. In some cases one or more of the I/O requests 
contained in the list may fail. Failure of an individual request does not prevent completion of 
any other individual request. To determine the outcome of each I/O request, the application I 
shall examine the error status associated with each aiocb control block. The error statuses so I 
returned are identical to those returned as the result of an aio_read () or aio_zvrite( ) function. 


ERRORS 

The liojistio () function shall fail if: 


MAN 


[EAGAIN] 


[EAGAIN] 

[EINVAL] 

[EINTR] 


[EIO] 


The resources necessary to queue all the I/O requests were not available. The 
application may check the error status for each aiocb to determine the 
individual request(s) that failed. 

The number of entries indicated by nent would cause the system-wide limit 
{AIO_MAX} to be exceeded. 

The mode argument is not a proper value, or the value of nent was greater than 
{AIO_LISTIO_M AX}. 

A signal was delivered while waiting for all I/O requests to complete during 
an LIO_WAIT operation. Note that, since each I/O operation invoked by 
liojistio () may possibly provoke a signal when it completes, this error return 
may be caused by the completion of one (or more) of the very I/O operations 
being awaited. Outstanding I/O requests are not canceled, and the application I 
shall examine each list element to determine whether the request was I 
initiated, canceled, or completed. 

One or more of the individual I/O operations failed. The application may 
check the error status for each aiocb structure to determine the individual 
request(s) that failed. 


In addition to the errors returned by the liojistio () function, if the liojistio () function succeeds 
or fails with errors of [EAGAIN], [EINTR], or [EIO], then some of the I/O specified by the list 
may have been initiated. If the liojistio () function fails with an error code other than [EAGAIN], 
[EINTR], or [EIO], no operations from the list shall have been initiated. The I/O operation 
indicated by each list element can encounter errors specific to the individual read or write 
function being performed. In this event, the error status for each aiocb control block contains the 
associated error code. The error codes that can be set are the same as would be set by a read() or 
ivrite( ) function, with the following additional error codes possible: 


[EAGAIN] The requested I/O operation was not queued due to resource limitations. 

[ECANCELED] The requested I/O was canceled before the I/O completed due to an explicit 
aio_cancel () request. 

[EFBIG] The aiocbp-^aioJio_opcode is LIO_WRITE, the file is a regular file, 

aiocbp-^aio_nbytes is greater than 0, and the aiocbp-^aiojoffset is greater than or 
equal to the offset maximum in the open file description associated with 
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20967 aiocbp-^aiojildes. 

20968 [EINPROGRESS] The requested I/O is in progress. 

20969 man [EOVERFLOW] The aiocbp—>aio_lio_opcode is LIO_READ, the file is a regular file, 

20970 aiocbp-)aio_nbytes is greater than 0, and the aiocbp-^aio_offset is before the 

20971 end-of-file and is greater than or equal to the offset maximum in the open file 

20972 description associated with aiocbp-^aiojildes . 

20973 EXAMPLES 

20974 None. 

20975 APPLICATION USAGE 

20976 None. 

20977 RATIONALE 

20978 Although it may appear that there are inconsistencies in the specified circumstances for error 

20979 codes, the [EIO] error condition applies when any circumstance relating to an individual 

20980 operation makes that operation fail. This might be due to a badly formulated request (for 

20981 example, the aio_lio_opcode field is invalid, and aio_error( ) returns [EINVAL]) or might arise from 

20982 application behavior (for example, the file descriptor is closed before the operation is initiated, 

20983 and aio_error( ) returns [EBADF]). 

20984 The limitation on the set of error codes returned when operations from the list shall have been 

20985 initiated enables applications to know when operations have been started and whether 

20986 aio_error( ) is valid for a specific operation. 

20987 FUTURE DIRECTIONS 

20988 None. 

20989 SEE ALSO 

20990 aio_read(), aio_write(), aio_error(), aio_return(), aio_cancel(), close(), _exit(), exec, fork(), lseek(), 

20991 read(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <aio.h> 

20992 CHANGE HISTORY 

20993 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

20994 Large File Summit extensions are added. 

20995 Issue 6 

20996 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

20997 implementation does not support the 

20998 The lio_listio () function is marked as part of the _POSIX_ASYNCHRONOUS_IO option. 

20999 The following new requirements on POSIX implementations derive from alignment with the 

21000 Single UNIX Specification: 

21001 • In the DESCRIPTION, text is added to indicate that for regular files no data transfer occurs 

21002 past the offset maximum established in the open file description associated with 

21003 aiocbp-^aiojildes. This change is to support large files. 

21004 • The [EBIG] and [EOVERFLOW] error conditions are defined. This change is to support large 

21005 files. 

21006 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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21007 NAME 

21008 listen — listen for socket connections and limit the queue of incoming connections 

21009 SYNOPSIS 

21010 tinclude <sys/socket.h> 

21011 int listen (int socket, int backlog) ; 

21012 DESCRIPTION 

21013 The listen () function shall mark a connection-mode socket, specified by the socket argument, as 

21014 accepting connections. 

21015 The backlog argument provides a hint to the implementation which the implementation shall use 

21016 to limit the number of outstanding connections in the socket's listen queue. Implementations 

21017 may impose a limit on backlog and silently reduce the specified value. Normally, a larger backlog 

21018 argument value shall result in a larger or equal length of the listen queue. Implementations shall 

21019 support values of backlog up to SOMAXCONN, defined in <sys/socket.h>. 

21020 The implementation may include incomplete connections in its listen queue. The limits on the 

21021 number of incomplete connections and completed connections queued may be different. 

21022 The implementation may have an upper limit on the length of the listen queue—either global or 

21023 per accepting socket. If backlog exceeds this limit, the length of the listen queue is set to the limit. 

21024 If listen () is called with a backlog argument value that is less than 0, the function behaves as if it 

21025 had been called with a backlog argument value of 0. 

21026 A backlog argument of 0 may allow the socket to accept connections, in which case the length of 

21027 the listen queue may be set to an implementation-dependent minimum value. 

21028 The socket in use may require the process to have appropriate privileges to use the listen() 

21029 function. 

21030 RETURN VALUE 

21031 Upon successful completions, listen () shall return 0; otherwise, -1 shall be returned and errno set 

21032 to indicate the error. 

21033 ERRORS 

21034 The listen () function shall fail if: 

21035 [EBADF] The socket argument is not a valid file descriptor. 

21036 [EDESTADDRREQ] 

21037 The socket is not bound to a local address, and the protocol does not support 

21038 listening on an unbound socket. 

21039 [EINVAL] The socket is already connected. 

21040 [ENOTSOCK] The socket argument does not refer to a socket. 

21041 [EOPNOTSUPP] The socket protocol does not support listen (). 

21042 The listen () function may fail if: 

21043 [EACCES] The calling process does not have the appropriate privileges. 

21044 [EINVAL] The socket has been shut down. 

21045 [ENOBUFS] Insufficient resources are available in the system to complete the call. 
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21046 EXAMPLES 

21047 None. 

21048 APPLICATION USAGE 

21049 None. 

21050 RATIONALE 

21051 None. 

21052 FUTURE DIRECTIONS 

21053 None. 

21054 SEE ALSO 

21055 accept (), connect(), socket (), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

21056 <sys/socket.h> 

21057 CHANGE HISTORY 

21058 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 

21059 The DESCRIPTION is updated to describe the relationship of SOMAXCONN and the backlog 

21060 argument. 
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21061 NAME 

21062 localeconv — determine the program locale 

21063 SYNOPSIS 

21064 #include <locale.h> 

21065 struct lconv *localeconv (void) ; 

21066 DESCRIPTION 

21067 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

21068 conflict between the requirements described here and the ISO C standard is unintentional. This I 

21069 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

21070 The localeconv () function shall set the components of an object with the type struct lconv with 

21071 the values appropriate for the formatting of numeric quantities (monetary and otherwise) 

21072 according to the rules of the current locale. 

21073 The members of the structure with type char* are pointers to strings, any of which (except 

21074 decimal_point) can point to " ", to indicate that the value is not available in the current locale or 

21075 is of zero length. The members with type char are non-negative numbers, any of which can be 

21076 {CHAR_MAX} to indicate that the value is not available in the current locale. 

21077 The members include the following: 

21078 char *decimal_point 

21079 The radix character used to format non-monetary quantities. 

21080 char *thousands_sep 

21081 The character used to separate groups of digits before the decimal-point character in 

21082 formatted non-monetary quantities. 

21083 char *grouping 

21084 A string whose elements taken as one-byte integer values indicate the size of each group of 

21085 digits in formatted non-monetary quantities. 

21086 char *int_curr_symbol 

21087 The international currency symbol applicable to the current locale. The first three 

21088 characters contain the alphabetic international currency symbol in accordance with those 

21089 specified in the ISO 4217:1995 standard. The fourth character (immediately preceding the 

21090 null byte) is the character used to separate the international currency symbol from the 

21091 monetary quantity. 

21092 char *currency_symbol 

21093 The local currency symbol applicable to the current locale. 

21094 char *mon_decimal_point 

21095 The radix character used to format monetary quantities. 

21096 char *mon_thousands_sep 

21097 The separator for groups of digits before the decimal-point in formatted monetary 

21098 quantities. 

21099 char hnon grouping 

21100 A string whose elements taken as one-byte integer values indicate the size of each group of 

21101 digits in formatted monetary quantities. 

21102 char *positive_sign 

21103 The string used to indicate a non-negative valued formatted monetary quantity. 
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21104 

21105 

21106 

21107 

21108 

21109 

21110 
21111 

21112 

21113 

21114 

21115 

21116 

21117 

21118 

21119 

21120 
21121 

21122 

21123 

21124 

21125 

21126 

21127 

21128 

21129 

21130 

21131 

21132 

21133 

21134 

21135 

21136 

21137 

21138 

21139 

21140 

21141 

21142 

21143 

21144 

21145 


XSI 

XSI 

XSI 

XSI 

XSI 

XSI 


XSI 

XSI 

XSI 

XSI 

XSI 


char *negative_sign 

The string used to indicate a negative valued formatted monetary quantity. 

char int_frac_digits 

The number of fractional digits (those after the decimal-point) to be displayed in an 
internationally formatted monetary quantity. 

char frac_digits 

The number of fractional digits (those after the decimal-point) to be displayed in a 
formatted monetary quantity. 

char p_cs_precedes 

Set to 1 if the currency_symbol or int_curr_symbol precedes the value for a non-negative 
formatted monetary quantity. Set to 0 if the symbol succeeds the value. 

char p_sep_by_space 

Set to 0 if no space separates the currency_symbol or int_curr_symbol from the value for a 
non-negative formatted monetary quantity. Set to 1 if a space separates the symbol from the 
value; and set to 2 if a space separates the symbol and the sign string, if adjacent. 

char n_cs_precedes 

Set to 1 if the currency_symbol or int_curr_symbol precedes the value for a negative 
formatted monetary quantity. Set to 0 if the symbol succeeds the value. 

char n_sep_by_space 

Set to 0 if no space separates the currency_symbol or int_curr_symbol from the value for a 
negative formatted monetary quantity. Set to 1 if a space separates the symbol from the 
value; and set to 2 if a space separates the symbol and the sign string, if adjacent. 

char p_sign_posn 

Set to a value indicating the positioning of the positive_sign for a non-negative formatted 
monetary quantity. 

char n_sign_posn 

Set to a value indicating the positioning of the negative_sign for a negative formatted 
monetary quantity. 

The elements of grouping and mon_grouping are interpreted according to the following: 
{CHAR_MAX} No further grouping is to be performed. 

0 The previous element is to be repeatedly used for the remainder of the digits. 

other The integer value is the number of digits that comprise the current group. The 

next element is examined to determine the size of the next group of digits 
before the current group. 

The values of p_sign_posn and n_sign_posn are interpreted according to the following: 

0 Parentheses surround the quantity and currency_symbol or int_curr_symbol. 

1 The sign string precedes the quantity and currency_symbol or int_curr_symbol. 

2 The sign string succeeds the quantity and currency_symbol or int_curr_symbol. 

3 The sign string immediately precedes the currency_symbol or int_curr_symbol. 

4 The sign string immediately succeeds the currency_symbol or int_curr_symbol. 

The implementation shall behave as if no function in this volume of IEEE Std. 1003.1-200x calls 
localeconv(). 
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21146 cx The localeconv() function need not be reentrant. A function that is not required to be reentrant is 

21147 not required to be thread-safe. 

21148 RETURN VALUE 

21149 The localeconvO function shall return a pointer to the filled-in object. The application shall not I 

21150 modify the structure pointed to by the return value which may be overwritten by a subsequent I 

21151 call to localeconvO■ In addition, calls to setlocale( ) with the categories LC_ALL, LC_MONETARY, I 

21152 or LC_NUMERIC may overwrite the contents of the structure. 

21153 ERRORS 

21154 No errors are defined. 

21155 EXAMPLES 

21156 None. 

21157 APPLICATION USAGE 

21158 The following table illustrates the rules which may be used by four countries to format monetary 

21159 quantities. 


21160 

Country 

Positive Format 

Negative Format 

International Format 

21161 

Italy 

L. 1.230 

-L. 1.230 

ITL.1.230 

21162 

Netherlands 

F 1.234,56 

F-1.234,56 

NLG 1.234,56 

21163 

Norway 

kr1.234,56 

kr1.234,56- 

NOK 1.234,56 

21164 

Switzerland 

SFrs.1,234.56 

SFrs.l,234.56C 

CHF 1,234.56 


21165 For these four countries, the respective values for the monetary members of the structure 

21166 returned by localeconv () are: 


21167 


Italy 

Netherlands 

Norway 

Switzerland 

21168 

int_curr_symbol 

" ITL . " 

"NLG " 

"NOK " 

"CHF " 

21169 

currency_symbol 

" L . " 

lip II 

"kr" 

"SFrs." 

21170 

mon_decimal_point 

II II 

II II 

r 

II II 

r 

II II 

21171 

mon_thousands_sep 

II II 

ii ii 

ii ii 

II II 

r 

21172 

mon_grouping 

" \ 3 " 

" \ 3 " 

" \ 3 " 

" \ 3 " 

21173 

positive_sign 

II II 

II II 

II II 

II II 

21174 

negative_sign 

II _ II 

II _ II 

II _ II 

"C" 

21175 

int_frac_digits 

0 

2 

2 

2 

21176 

frac_digits 

0 

2 

2 

2 

21177 

p_cs_precedes 

1 

1 

1 

1 

21178 

p_sep_by_space 

0 

1 

0 

0 

21179 

n_cs_precedes 

1 

1 

1 

1 

21180 

n_sep_by_space 

0 

1 

0 

0 

21181 

p_sign_posn 

1 

1 

1 

1 

21182 

n_sign_posn 

1 

4 

2 

2 


21183 RATIONALE 

21184 None. 

21185 FUTURE DIRECTIONS 

21186 None. 

21187 SEE ALSO 

21188 isalphaO, isascii (), nl_langinfo0 , printfO , scanfO, setlocaleO, strcatO, strchr() r strcmpO / strcollO/ 

21189 strcpy (), strftimeO, strlenO, strpbrk (), strspnO , strtokO , strxfrmO, strtodO , the System Interface 

21190 Definitions volume of IEEE Std. 1003.1-200x, <langinfo.h>, <locale.h> 
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21191 

21192 

21193 

21194 

21195 

21196 


CHANGE HISTORY 

First released in Issue 4. 

Derived from the ANSI C standard. 

Issue 6 

A note indicating that this function need not be reentrant is added to the DESCRIPTION. 
The RETURN VALUE section is rewritten to avoid use of the term "must”. 
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21197 NAME 

21198 localtime, localtime_r — convert a time value to a broken-down local time 

21199 SYNOPSIS 

21200 #include <time.h> 

21201 struct tm *localtime(const time_t *timer); 

21202 TSF struct tm *localtime_r(const time_t * clock, struct tm * result) ; 

21203 

21204 DESCRIPTION 

21205 cx For localtime(): The functionality described on this reference page is aligned with the ISOC 

21206 standard. Any conflict between the requirements described here and the ISO C standard is I 

21207 unintentional. This volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

21208 The localtime() function shall convert the time in seconds since the Epoch pointed to by timer 

21209 into a broken-down time, expressed as a local time. The function corrects for the timezone and 

21210 any seasonal time adjustments. Local timezone information is used as though localtimeO calls 

21211 tzsetO- 

21212 cx The localtimeO function need not be reentrant. A function that is not required to be reentrant is 

21213 not required to be thread-safe. 

21214 tsf The localtimejrO function shall convert the calendar time pointed to by clock into a broken-down 

21215 time stored in the structure to which result points. The localtime_r( ) function shall also return a 

21216 pointer to that same structure. 

21217 Unlike localtime (), the reentrant version is not required to set tzname. 

21218 RETURN VALUE 

21219 The localtime () function shall return a pointer to the broken-down time structure. 

21220 tsf Upon successful completion, localtime_rO shall return a pointer to the structure pointed to by 

21221 the argument result. 

21222 ERRORS 

21223 No errors are defined. 

21224 EXAMPLES 

21225 Getting the Local Date and Time 

21226 The following example uses the time( ) function to calculate the time elapsed, in seconds, since 

21227 January 1, 1970 0:00 UTC (the Epoch), localtimeO to convert that value to a broken-down time, 

21228 and asctime( ) to convert the broken-down time values into a printable string. 

21229 #include <stdio.h> 

21230 #include <time.h> 

21231 main () 

21232 { 

21233 time_t result; 

21234 result = time (NULL) ; 

21235 printf ("%s%ld secs since the Epoch\n", 

21236 asctime (localtime (Sresult) ) , 

21237 (long) result) ; 

21238 return (0); 

21239 } 
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21240 This example writes the current time to stdout in a form like this: 

21241 Wed Jun 26 10:32:15 1996 

21242 835810335 secs since the Epoch 

21243 Getting the Modification Time for a File 

21244 The following example gets the modification time for a file. The localtime () function converts the 

21245 time_t value of the last modification date, obtained by a previous call to stat( ), into a tm 

21246 structure that contains the year, month, day, and so on. 

21247 #include <time.h> 

21248 

21249 struct stat statbuf; 

21250 

21251 tm = localtime (Sstatbuf. st_mtime) ; 

21252 

21253 Timing an Event 

21254 The following example gets the current time, converts it to a string using localtime () and 

21255 asctimei ), and prints it to standard output using fputs(). It then prints the number of minutes to 

21256 an event being timed. 

21257 #include <time.h> 

21258 #include <stdio.h> 

21259 

21260 time_t now; 

21261 int minutes_to_event; 

21262 

21263 time (Snow) ; 

21264 printf ("The time is "); 

21265 fputs (asctime (localtime (Snow)), stdout); 

21266 printf ("There are still %d minutes to the event.\n", 

21267 minutes_to_event) ; 

21268 

21269 APPLICATION USAGE 

21270 The asctimei ), ctime{ ), getdate( ), gettimeofday (), gmtime( ), and localtime () functions return values 

21271 in one of two static objects: a broken-down time structure and an array of char. Execution of any 

21272 of the functions may overwrite the information returned in either of these objects by any of the 

21273 other functions. 

21274 The localtime_r( ) function is thread-safe and shall return values in a user-supplied buffer instead 

21275 of possibly using a static data area that may be overwritten by each call. 

21276 RATIONALE 

21277 None. 

21278 FUTURE DIRECTIONS 

21279 None. 

21280 SEE ALSO 

21281 asctime{), clocki), ctimei), difftimei), getdatei), gettimeofday (), gmtimei), mktimei), strftimei), 

21282 strptimei), timei ), utimei), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

21283 <time.h> 
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CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The APPLICATION USAGE section is expanded to provide a more complete description of how 
static areas are used by the *time () functions. 

The following change is incorporated for alignment with the ISO C standard: 

• The timer argument is now a type const time_t 

Issue 5 

A note indicating that the localtime() function need not be reentrant is added to the 
DESCRIPTION. 

The localtime_r{) function is included for alignment with the POSIX Threads Extension. 

Issue 6 

The localtime_r () function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS 
option. 

Extensions beyond the ISO C standard are now marked. 

The APPLICATION USAGE section is updated to include a note on the thread-safe function and 
its avoidance of possibly using a static data area. 
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21302 NAME 

21303 lockf — record locking on files 

21304 SYNOPSIS 

21305 xsi tinclude <unistd.h> 

21306 int lockf (int fildes, int function, off_t size) ; 

21307 

21308 DESCRIPTION 

21309 The lockf () function allows sections of a file to be locked with advisory-mode locks. Calls to 

21310 lockf () from other threads which attempt to lock the locked file section shall either return an 

21311 error value or block until the section becomes unlocked. All the locks for a process are removed 

21312 when the process terminates. Record locking with lockf ( ) is supported for regular files and may 

21313 be supported for other files. 

21314 Th e fildes argument is an open file descriptor. The application shall ensure that the file descriptor I 

21315 has been opened with write-only permission (0_WRONLY) or with read/write permission I 

21316 (0_RDWR) to establish a lock with this function. 

21317 The function argument is a control value which specifies the action to be taken. The permissible 

21318 values for function are defined in <unistd.h> as follows: 

21319 


21320 

Function 

Description 

21321 

F_ULOCK 

Unlock locked sections. 

21322 

F_LOCK 

Lock a section for exclusive use. 

21323 

F_TLOCK 

Test and lock a section for exclusive use. 

21324 

F_TEST 

Test a section for locks by other processes. 


21325 F_TEST detects if a lock by another process is present on the specified section. 

21326 F_LOCK and F_TLOCK both lock a section of a file if the section is available. 

21327 F_ULOCK removes locks from a section of the file. 

21328 The size argument is the number of contiguous bytes to be locked or unlocked. The section to be 

21329 locked or unlocked starts at the current offset in the file and extends forward for a positive size 

21330 or backward for a negative size (the preceding bytes up to but not including the current offset). 

21331 If size is 0, the section from the current offset through the largest possible file offset is locked 

21332 (that is, from the current offset through the present or any future end-of-file). An area need not 

21333 be allocated to the file to be locked because locks may exist past the end-of-file. 

21334 The sections locked with F_LOCK or F_TLOCK may, in whole or in part, contain or be contained 

21335 by a previously locked section for the same process. When this occurs, or if adjacent locked 

21336 sections would occur, the sections are combined into a single locked section. If the request 

21337 would cause the number of locks to exceed a system-imposed limit, the request shall fail. 

21338 F_LOCK and F_TLOCK requests differ only by the action taken if the section is not available. 

21339 F_LOCK blocks the calling thread until the section is available. F_TLOCK makes the function 

21340 fail if the section is already locked by another process. 

21341 File locks are released on first close by the locking process of any file descriptor for the file. 

21342 F_ULOCK requests may release (wholly or in part) one or more locked sections controlled by the 

21343 process. Locked sections shall be unlocked starting at the current file offset through size bytes or 

21344 to the end-of-file if size is (off_t)0. When all of a locked section is not released (that is, when the 

21345 beginning or end of the area to be unlocked falls within a locked section), the remaining portions 

21346 of that section are still locked by the process. Releasing the center portion of a locked section 
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shall cause the remaining locked beginning and end portions to become two separate locked 
sections. If the request would cause the number of locks in the system to exceed a system- 
imposed limit, the request shall fail. 

A potential for deadlock occurs if the threads of a process controlling a locked section are 
blocked by accessing another process' locked section. If the system detects that deadlock would 
occur, lockf () shall fail with an [EDEADLK] error. 

The interaction between fcntl() and lockf () locks is unspecified. 

Blocking on a section is interrupted by any signal. 

An F_ULOCK request in which size is non-zero and the offset of the last byte of the requested 
section is the maximum value for an object of type off_t, when the process has an existing lock 
in which size is 0 and which includes the last byte of the requested section, shall be treated as a 
request to unlock from the start of the requested section with a size equal to 0. Otherwise, an 
F_ULOCK request shall attempt to unlock only the requested section. 

Attempting to lock a section of a file that is associated with a buffered stream produces 
unspecified results. 

RETURN VALUE 

Upon successful completion, lockf () shall return 0. Otherwise, it shall return -1, set errno to 
indicate an error, and existing locks shall not be changed. 


ERRORS 

The lockf () function shall fail if: 

[EBADF] The fildes argument is not a valid open file descriptor; or function is F_LOCK 

or F_TLOCK and fildes is not a valid file descriptor open for writing. 


[EACCES] or [EAGAIN] 

The function argument is F_TLOCK or F_TEST and the section is already 
locked by another process. 

[EDEADLK] The function argument is F_LOCK and a deadlock is detected. 

[EINTR] A signal was caught during execution of the function. 

[EINVAL] The function argument is not one of F_LOCK, F_TLOCK, F_TEST, or 

F_ULOCK; or size plus the current file offset is less than 0. 

[EOVERFLOW] The offset of the first, or if size is not 0 then the last, byte in the requested 
section cannot be represented correctly in an object of type off_t. 

The lockf () function may fail if: 

[EAGAIN] The function argument is F_LOCK or F_TLOCK and the file is mapped with 

mmap(). 


[EDEADLK] or [ENOLCK] 

The function argument is F_LOCK, F_TLOCK, or F_ULOCK, and the request 
would cause the number of locks to exceed a system-imposed limit. 

[EOPNOTSUPP] or [EINVAL] 

The implementation does not support the locking of files of the type indicated 
by th e fildes argument. 
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EXAMPLES 

Locking a Portion of a File 

In the following example, a file named /home/cnd/modl is being modified. Other processes that 
use locking are prevented from changing it during this process. Only the first 10,000 bytes are 
locked, and the lock call fails if another process has any part of this area locked already. 

#include <fcntl.h> 

#include <unistd.h> 

int fildes; 
int status; 

fildes = open("/home/cnd/modl", 0_RDWR); 
status = lockf(fildes, F_TLOCK, (off_t)10000); 

APPLICATION USAGE 

Record-locking should not be used in combination with the /open (), /read (),fwrite(), and other 
stdio functions. Instead, the more primitive, non-buffered functions (such as open ()) should be 
used. Unexpected results may occur in processes that do buffering in the user address space. The 
process may later read/write data which is/was locked. The stdio functions are the most 
common source of unexpected buffering. 

The alarm () function may be used to provide a timeout facility in applications requiring it. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

alarm(), chmod(), close(), creat(), fcntl(), fopen(), mmap(), open(), read(), zvrite(), the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 

Large File Summit extensions are added. In particular, the description of [EINVAL] is clarified 
and moved from optional to mandatory status. 

A note is added to the DESCRIPTION indicating the effects of attempting to lock a section of a 
file that is associated with a buffered stream. 

Issue 6 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 


680 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


21423 

21424 

21425 

21426 

21427 

21428 

21429 

21430 

21431 

21432 

21433 

21434 

21435 

21436 

21437 

21438 

21439 

21440 

21441 

21442 

21443 

21444 

21445 

21446 

21447 

21448 

21449 

21450 

21451 

21452 

21453 

21454 

21455 

21456 

21457 

21458 

21459 

21460 

21461 


log() 


NAME 

log — natural logarithm function 

SYNOPSIS 

#include <math.h> 

double log(double x) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The log () function shall compute the natural logarithm of x, log e (x). The application shall ensure I 
that the value of x is positive. I 

An application wishing to check for error situations should set errno to 0 before calling log (). If 
errno is non-zero on return, or the return value is NaN, an error has occurred. 

RETURN VALUE 

Upon successful completion, log () shall return the natural logarithm of x. 
xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

xsi If x is less than 0, -HUGE_VAL or NaN shall be returned,and errno shall be set to [EDOM]. 

If x is 0, -HUGE_VAL shall be returned and errno may be set to [ERANGE]. 

ERRORS 

The log () function shall fail if: 

[EDOM] The value of x is negative. 

The log () function may fail if: 
xsi [EDOM] The value of x is NaN. 

[ERANGE] The value of x is 0. 

xsi No other errors shall occur. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

exp (), isnan (), logl0 (), loglp (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

<math.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 
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Issue 4 

References to matherr () are removed. 

The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 
ISO C standard and to rationalize error handling in the mathematics functions. 

The return value specified for [EDOM] is marked as an extension. 

Issue 5 

The DESCRIPTION is updated to indicate how an application should check for an error. This 
text was previously published in the APPLICATION USAGE section. 

Issue 6 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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NAME 

loglO — base 10 logarithm function 

SYNOPSIS 

#include <math.h> 

double loglO(double x); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The logl0() function shall compute the base 10 logarithm of x, log iQ (x). The application shall I 
ensure that the value of x is positive. I 

An application wishing to check for error situations should set errno to 0 before calling loglO (). 

If errno is non-zero on return, or the return value is NaN, an error has occurred. 

RETURN VALUE 

Upon successful completion, logl0 () shall return the base 10 logarithm of x. 
xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

xsi If x is less than 0, -HUGE_VAL or NaN shall be returned,and errno shall be set to [EDOM]. 

If x is 0, -HUGE_VAL shall be returned and errno may be set to [ERANGE]. 

ERRORS 

The loglO () function shall fail if: 

[EDOM] The value of x is negative. 

The loglO () function may fail if: 
xsi [EDOM] The value of x is NaN. 

[ERANGE] The value of x is 0. 

xsi No other errors shall occur. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

isnan (), log (), pow {), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

<math.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 
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Issue 4 

References to matherr () are removed. 

The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 
ISO C standard and to rationalize error handling in the mathematics functions. 

The return value specified for [EDOM] is marked as an extension. 

Issue 5 

The DESCRIPTION is updated to indicate how an application should check for an error. This 
text was previously published in the APPLICATION USAGE section. 

Issue 6 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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21521 NAME 

21522 loglp — compute a natural logarithm 

21523 SYNOPSIS 

21524 xsi tinclude <math.h> 

21525 double loglp (double x) ; 

21526 

21527 DESCRIPTION 

21528 The loglp () function shall compute log (1.0 + x). The application shall ensure that the value of x I 

21529 is greater than-1.0. I 

21530 RETURN VALUE 

21531 Upon successful completion, loglp () shall return the natural logarithm of 1.0 + x. 

21532 If x is NaN, loglp () shall return NaN and may set errno to [EDOM], 

21533 If x is less than-1.0, loglp() shall return-HUGE_VAL or NaN and set errno to [EDOM]. 

21534 If x is —1.0, loglp () shall return-HUGE_VAL and may set errno to [ERANGE]. 

21535 ERRORS 

21536 The loglp () function shall fail if: 

21537 [EDOM] The value of x is less than-1.0. 

21538 The loglp () function may fail and set errno to: 

21539 [EDOM] The value of x is NaN. 

21540 [ERANGE] The value ofx is-1.0. 

21541 No other errors shall occur. 

21542 EXAMPLES 

21543 None. 

21544 APPLICATION USAGE 

21545 None. 

21546 RATIONALE 

21547 None. 

21548 FUTURE DIRECTIONS 

21549 None. 

21550 SEE ALSO 

21551 log( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

21552 CHANGE HISTORY 

21553 First released in Issue 4, Version 2. 

21554 Issue 5 

21555 Moved from X/OPEN UNIX extension to BASE. I 

21556 Issue 6 I 

21557 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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NAME 

logb — radix-independent exponent 

SYNOPSIS 

xsi tinclude <math.h> 

double logb(double x) ; 

DESCRIPTION 

The logb () function shall compute the exponent of x, which is the integral part of log ; , | x \, as a 
signed floating point value, for non-zero x, where r is the radix of the machine's floating-point 
arithmetic. 

RETURN VALUE 

Upon successful completion, logb() shall return the exponent of x. 

If x is 0.0, logb () shall return -HUGE_VAL and set errno to [EDOM], 

If x is ±Inf, logb () shall return +Inf. 

If x is NaN, logb() shall returnNaN and may set errno to [EDOM], 

ERRORS 

The logb () function shall fail if: 

[EDOM] The x argument is 0.0. 

The logb () function may fail if: 

[EDOM] The x argument is NaN. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

ilogb (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 
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21592 NAME 

21593 longjmp — non-local goto 

21594 SYNOPSIS 

21595 tinclude <setjmp.h> 

21596 void long jmp ( jmp_buf env, int val) ; 

21597 DESCRIPTION 

21598 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

21599 conflict between the requirements described here and the ISO C standard is unintentional. This I 

21600 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

21601 The longjmpO function shall restore the environment saved by the most recent invocation of 

21602 set jmp () in the same thread, with the corresponding jmp_buf argument. If there is no such 

21603 invocation, or if the function containing the invocation of setjmp () has terminated execution in 

21604 cx the interim, the behavior is undefined. It is unspecified whether longjmp () restores the signal 

21605 mask, leaves the signal mask unchanged, or restores it to its value at the time setjmp () was 

21606 called. 

21607 All accessible objects have values as of the time setjmp 0 was called, except that the values of 

21608 objects of automatic storage duration are indeterminate if they meet all the following conditions: 

21609 • They are local to the function containing the corresponding setjmp () invocation. 

21610 • They do not have volatile-qualified type. 

21611 • They are changed between the setjmp () invocation and longjmp () call. 

21612 As it bypasses the usual function call and return mechanisms, longjmp () shall execute correctly 

21613 in contexts of interrupts, signals, and any of their associated functions. However, if longjmpO is 

21614 invoked from a nested signal handler (that is, from a function invoked as a result of a signal 

21615 raised during the handling of another signal), the behavior is undefined. 

21616 cx The effect of a call to longjmpO where initialization of the jmpjbuf structure was not performed 

21617 in the calling thread is undefined. 

21618 RETURN VALUE 

21619 After longjmp () is completed, program execution continues as if the corresponding invocation of 

21620 setjmp 0 had just returned the value specified by ml. The longjmp () function shall not cause 

21621 setjmp () to return 0; if veil is 0, setjmp () shall return 1. 

21622 ERRORS 

21623 No errors are defined. 

21624 EXAMPLES 

21625 None. 

21626 APPLICATION USAGE 

21627 Applications whose behavior depends on the value of the signal mask should not use longjmp () 

21628 and setjmp 0, since their effect on the signal mask is unspecified, but should instead use the 

21629 siglongjmp () and sigsetjmp () functions (which can save and restore the signal mask under 

21630 application control). 

21631 RATIONALE 

21632 None. 
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FUTURE DIRECTIONS 

None. 

SEE ALSO 

setjmp (), sigaction{), siglongjmpO, sigsetjmp(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <setjmp.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The APPLICATION USAGE section is deleted. 

The following change is incorporated for alignment with the ISO C standard: 

• Mention of volatile-qualified types is added to the DESCRIPTION. 

Issue 4, Version 2 

The DESCRIPTION is updated for X/OPEN UNIX conformance and discusses valid possibilities 
for the resulting state of the signal mask. 

Issue 5 

The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The DESCRIPTION now explicitly makes longjmpO's effect on the signal mask unspecified. 
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21655 NAME 

21656 lrand48 — generate uniformly distributed pseudo-random non-negative long integers 

21657 SYNOPSIS 

21658 xsi tinclude <stdlib.h> 

21659 long int lrand48 (void) ; 

21660 

21661 DESCRIPTION 

21662 Refer to drand48 (). 
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21663 NAME 

21664 lsearch, lfind — linear search and update 

21665 SYNOPSIS 

21666 xsi #include <search.h> 

21667 

21668 

21669 

21670 

21671 

21672 DESCRIPTION 

21673 The lsearch() function is a linear search routine. It returns a pointer into the table for the 

21674 matching entry. If the entry does not occur, it is added at the end of the table. The key argument 

21675 points to the entry to be sought in the table. The base argument points to the first element in the 

21676 table. The width argument is the size of an element in bytes. The nelp argument points to an 

21677 integer containing the current number of elements in the table. The integer to which nelp points 

21678 is incremented if the entry is added to the table. The compar argument points to a comparison I 

21679 function which the application shall supply (for example, strcmp ()). It is called with two I 

21680 arguments that point to the elements being compared. The application shall ensure that the I 

21681 function returns 0 if the elements are equal, and non-zero otherwise. I 

21682 The lfind 0 function is the same as lsearch () except that if the entry is not found, it is not added to 

21683 the table. Instead, a null pointer is returned. 

21684 RETURN VALUE 

21685 If the searched for entry is found, both lsearch () and lfind () shall return a pointer to it. Otherwise, 

21686 lfind () shall return a null pointer and lsearch () shall return a pointer to the newly added element. 

21687 Both functions shall return a null pointer in case of error. 

21688 ERRORS 

21689 No errors are defined. 

21690 EXAMPLES 

21691 Storing Strings in a Table 

21692 This fragment reads in less than or equal to TABSIZE strings of length less than or equal to 

21693 ELSIZE and stores them in a table, eliminating duplicates. 

21694 #include <stdio.h> 

21695 #include <string.h> 

21696 #include <search.h> 

21697 #define TABSIZE 50 

21698 #define ELSIZE 120 

21699 

21700 char line [ELSIZE] , tab [TABSIZE] [ELSIZE] ; 

21701 size_t nel = 0; 

21702 

21703 while (fgets(line, ELSIZE, stdin) != NULL && nel < TABSIZE) 

21704 (void) lsearch (line, tab, &nel, 

21705 ELSIZE, (int (*) (const void *, const void *)) strcmp); 

21706 


void *lsearch(const void *key, void *base, size_t *nelp, size_t width, 
int ( *compar) (const void *, const void *)); 
void *lfind(const void *key, const void *base, size_t *nelp, 
size_t width, int (* compar) (const void *, const void *)); 
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21707 Finding a Matching Entry 

21708 The following example finds any line that reads "This is a test.". 

21709 #include <search.h> 

21710 #include <string.h> 

21711 

21712 char line [ELSIZE] , tab [TABSIZE] [ELSIZE] ; 

21713 size_t nel = 0; 

21714 char *findline; 

21715 void *entry; 

21716 findline = "This is a test.Xn"; 

21717 entry = lfind (findline, tab, &nel, ELSIZE, ( 

21718 int (*) (const void *, const void *)) strcmp) ; 

21719 APPLICATION USAGE 

21720 The comparison function need not compare every byte, so arbitrary data may be contained in 

21721 the elements in addition to the values being compared. 

21722 Undefined results can occur if there is not enough room in the table to add a new item. 

21723 RATIONALE 

21724 None. 

21725 FUTURE DIRECTIONS 

21726 None. 

21727 SEE ALSO 

21728 hcreate( ), tsearch(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <search.h> 

21729 CHANGE HISTORY 

21730 First released in Issue 1. 

21731 Derived from Issue 1 of the SVID. 

21732 Issue 4 

21733 In the SYNOPSIS section, the type of argument key in the declaration of Isearch () is changed from 

21734 void 51 ' to const void*, the type arguments key and base have been changed from void 51 ' to const 

21735 void 51 ' in the declaration of lfind (), and the arguments to compar are defined for both functions. 

21736 In the EXAMPLES section, the sample code is updated to use ISO C standard syntax. 

21737 Warnings about the casting of various arguments are removed from the APPLICATION USAGE 

21738 section, as casting requirements are now clear from the function definitions. 

21739 Issue 6 

21740 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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21741 

21742 

21743 

21744 

21745 

21746 

21747 

21748 

21749 

21750 

21751 

21752 

21753 

21754 

21755 

21756 

21757 

21758 

21759 

21760 

21761 

21762 

21763 

21764 

21765 

21766 

21767 

21768 

21769 

21770 

21771 

21772 

21773 

21774 

21775 

21776 

21777 

21778 

21779 

21780 

21781 


NAME 

lseek — move the read/write file offset 

SYNOPSIS 

#include <unistd.h> 

off_t lseek(int fildes, off_t offset, int whence); 

DESCRIPTION 

The lseek () function shall set the file offset for the open file description associated with the file 
descriptor fildes, as follows: 

• If whence is {SEEK_SET}, the file offset is set to offset bytes. 

• If whence is {SEEK_CUR}, the file offset is set to its current location plus offset. 

• If whence is {SEEK_END}, the file offset is set to the size of the file plus offset. 

The symbolic constants {SEEK_SET[, {SEEK_CUR}, and |SEEK_END[ are defined in <unistd.h>. 

The behavior of lseek( ) on devices which are incapable of seeking is implementation-dependent. 
The value of the file offset associated with such a device is undefined. 

The lseek () function shall allow the file offset to be set beyond the end of the existing data in the 
file. If data is later written at this point, subsequent reads of data in the gap shall return bytes 
with the value 0 until data is actually written into the gap. 

The lseek( ) function shall not, by itself, extend the size of a file. 

shm If fildes refers to a shared memory object, the result of the lseek( ) function is unspecified. 

tym If fildes refers to a typed memory object, the result of the lseek () function is unspecified. 

RETURN VALUE 

Upon successful completion, the resulting offset, as measured in bytes from the beginning of the 
file, shall be returned. Otherwise, (off_t)-l shall be returned, errno shall be set to indicate the 
error, and the file offset shall remain unchanged. 

ERRORS 

The lseek () function shall fail if: 

[EBADF] Th e fildes argument is not an open file descriptor. 

[EINVAL] The whence argument is not a proper value, or the resulting file offset would 

be negative for a regular file, block special file, or directory. 

man [EOVERFLOW] The resulting file offset would be a value which cannot be represented 

correctly in an object of type off_t. 

[ESPIPE] Th e fildes argument is associated with a pipe, FIFO, or socket. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

The ISO C standard includes the functions fgetpos( ) and fsetpos(), which work on very large files 
by use of a special positioning type. 

Although lseek () may position the file offset beyond the end of the file, this function does not 
itself extend the size of the file. While the only function in this volume of IEEE Std. 1003.1-200x 
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21782 

21783 

21784 

21785 

21786 

21787 

21788 

21789 

21790 

21791 

21792 

21793 

21794 

21795 

21796 

21797 

21798 

21799 

21800 

21801 

21802 

21803 

21804 

21805 

21806 

21807 

21808 

21809 

21810 

21811 

21812 

21813 

21814 

21815 

21816 

21817 

21818 
21819 


that may directly extend the size of the file is write (), several functions originally derived from 
the ISO C standard, such as fzvrite( ),fprintf (), and so on, may do so (by causing calls on ivrite ()). 

An invalid file offset that would cause [EINVAL] to be returned may be both implementation- 
dependent and device-dependent (for example, memory may have few invalid values). A 
negative file offset may be valid for some devices in some implementations. 

The POSIX.1-1990 standard did not specifically prohibit lseek () from returning a negative offset. 
Therefore, an application was required to clear errno prior to the call and check errno upon return 
to determine whether a return value of (off_t)-l is a negative offset or an indication of an error 
condition. The standard developers did not wish to require this action on the part of a portable 
application, and chose to require that errno be set to [EINVAL] when the resulting file offset 
would be negative for a regular file, block special file, or directory. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

open(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, <sys/types.h>, 
<unistd.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 
XSI-conformant systems. 

The APPLICATION USAGE section is removed, as the ISO POSIX-1 standard now requires that 
off_t be signed. 

Issue 5 

The DESCRIPTION is updated for alignment with the POSIX Realtime Extension. 

Large File Summit extensions are added. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• The [EOVERFLOW] error condition is added. This change is to support large files. 

An additional [ESPIPE] error condition is added for sockets. I 

The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that I 
lseek () results are unspecified for typed memory objects. I 
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21820 NAME 

21821 lstat — get symbolic link status 

21822 SYNOPSIS 

21823 tinclude <sys/stat.h> 

21824 int lstat (const char *path, struct stat *buf) ; 

21825 DESCRIPTION 

21826 The lstat () function shall have the same effect as stat(), except when path refers to a symbolic 

21827 link. In that case lstat () shall return information about the link, while stat() shall return 

21828 information about the file the link references. 

21829 For symbolic links, the stjnode member shall contain meaningful information when used with 

21830 the file type macros, and the st_size member shall contain the length of the path name contained 

21831 in the symbolic link. File mode bits and the contents of the remaining members of the stat 

21832 structure are unspecified. The value returned in the st_size member is the length of the contents 

21833 of the symbolic link, and does not count any trailing null. 

21834 RETURN VALUE 

21835 Upon successful completion, lstat () shall return 0. Otherwise, it shall return -1 and set errno to 

21836 indicate the error. 


21837 ERRORS 

21838 The lstat() 

21839 [EACCES] 

21840 [EIO] 

21841 [ELOOP] 

21842 


function shall fail if: 

A component of the path prefix denies search permission. 

An error occurred while reading from the file system. 

A loop exists in symbolic links encountered during resolution of the path 
argument. 


21843 

21844 

21845 


[ENAMETOOLONG] 

The length of a path name exceeds |PATH_MAX}, or path name component is 
longer than {NAME_MAX}. 


21846 

21847 

21848 

21849 

21850 


[ENOTDIR] A component of the path prefix is not a directory. 

[ENOENT] A component of path does not name an existing file or path is an empty string. 

[EOVERFLOW] The file size in bytes or the number of blocks allocated to the file or the file 
serial number cannot be represented correctly in the structure pointed to by 
huf. 


21851 

21852 

21853 

21854 

21855 

21856 

21857 

21858 


The lstat () function may fail if: 

[ELOOP] More than ]SYMLOOP_MAX] symbolic links were encountered during 

resolution of the path argument. 

[ENAMETOOLONG] 

As a result of encountering a symbolic link in resolution of the path argument, 
the length of the substituted path name string exceeded ]PATH_MAX[. 

[EOVERFLOW] One of the members is too large to store into the structure pointed to by the 
buf argument. 
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21859 EXAMPLES 

21860 Obtaining Symbolic Link Status Information 

21861 The following example shows how to obtain status information for a symbolic link named 

21862 /modules/passl. The structure variable buffer is defined for the stat structure. If the path 

21863 argument specified the file name for the file pointed to by the symbolic link (/home/cnd/modl), 

21864 the results of calling the function would be the same as those returned by a call to the stat( ) 

21865 function. 

21866 #include <sys/stat.h> 

21867 struct stat buffer; 

21868 int status; 

21869 

21870 status = lstat ("/modules/passl" , Sbuffer); 

21871 APPLICATION USAGE 

21872 None. 

21873 RATIONALE 

21874 The lstat () function is not required to update the time-related fields if the named file is not a I 

21875 symbolic link. While the st_uid, st_gid, st_atime, stjntime, and st_ctime members of the stat I 

21876 structure may apply to a symbolic link, they are not required to do so. No functions in I 

21877 IEEE Std. 1003.1-200x are required to maintain any of these time fields. I 

21878 EUTURE DIRECTIONS 

21879 None. 

21880 SEE ALSO 

21881 fstat(), readlink(), stat(), symlink(), the System Interface Definitions volume of 

21882 IEEE Std. 1003.1-200x, <sys/stat.h> 

21883 CHANGE HISTORY 

21884 First released in Issue 4, Version 2. 

21885 Issue 5 

21886 Moved from X/OPEN UNIX extension to BASE. 

21887 Large File Summit extensions are added. I 

21888 Issue 6 I 

21889 The following changes were made to align with the IEEE P1003.1a draft standard: I 

21890 • This function is now mandatory. 

21891 • The [ELOOP] optional error condition is added. I 
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21892 NAME 

21893 makecontext, swapcontext — manipulate user contexts 

21894 SYNOPSIS 

21895 xsi #include <ucontext.h> 

21896 void makecontext (ucontext_t *ucp, (void *func) (), int argc, ...); 

21897 int swapcontext (ucontext_t *oucp, const ucontext_t *ucp) ; 

21898 

21899 DESCRIPTION 

21900 The makecontext{) function shall modify the context specified by ucp, which has been initialized 

21901 using getcontext(). When this context is resumed using szvapcontext () or set context ( ), program 

21902 execution shall continue by calling func, passing it the arguments that follow argc in the 

21903 makecontext () call. 

21904 Before a call is made to makecontext (), the application shall ensure that the context being I 

21905 modified has a stack allocated for it. The application shall ensure that the value of argc matches I 

21906 the number of integer arguments passed to fnnc; otherwise, the behavior is undefined. I 

21907 The uc_link member is used to determine the context that shall be resumed when the context 

21908 being modified by makecontext () returns. The application shall ensure that the ucjink member is I 

21909 initialized prior to the call to makecontext (). I 

21910 The szvapcontext () function shall save the current context in the context structure pointed to by 

21911 oucp and shall set the context to the context structure pointed to by ucp . 

21912 RETURN VALUE 

21913 Upon successful completion, szvapcontext () shall return 0. Otherwise, -1 shall be returned and I 

21914 errno set to indicate the error. 

21915 ERRORS 

21916 The szvapcontext () function shall fail if: 

21917 [ENOMEM] The ucp argument does not have enough stack left to complete the operation. 

21918 EXAMPLES 

21919 None. 

21920 APPLICATION USAGE 

21921 None. 

21922 RATIONALE 

21923 None. 

21924 FUTURE DIRECTIONS 

21925 None. 

21926 SEE ALSO 

21927 exit(), getcontext(), sigaction(), sigprocmask(), the System Interface Definitions volume of 

21928 IEEE Std. 1003.1-200x, <ucontext.h> 

21929 CHANGE HISTORY 

21930 First released in Issue 4, Version 2. 

21931 Issue 5 

21932 Moved from X/OPEN UNIX extension to BASE. 

21933 In the ERRORS section, the description of [ENOMEM] is changed to apply to szvapcontext () only. I 
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21934 Issue 6 

21935 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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21936 NAME 

21937 malloc — a memory allocator 

21938 SYNOPSIS 

21939 tinclude <stdlib.h> 

21940 void *malloc(size_t size); 

21941 DESCRIPTION 

21942 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

21943 conflict between the requirements described here and the ISO C standard is unintentional. This I 

21944 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

21945 The malloc () function shall allocate unused space for an object whose size in bytes is specified by 

21946 size and whose value is indeterminate. 

21947 The order and contiguity of storage allocated by successive calls to malloc () is unspecified. The 

21948 pointer returned if the allocation succeeds is suitably aligned so that it may be assigned to a 

21949 pointer to any type of object and then used to access such an object in the space allocated (until 

21950 the space is explicitly freed or reallocated). Each such allocation shall yield a pointer to an object 

21951 disjoint from any other object. The pointer returned points to the start (lowest byte address) of 

21952 the allocated space. If the space cannot be allocated, a null pointer is returned. If the size of the 

21953 space requested is 0, the behavior is implementation-dependent; the value returned is either a 

21954 null pointer or a unique pointer. 

21955 RETURN VALUE 

21956 Upon successful completion with size not equal to 0, malloc () shall return a pointer to the 

21957 allocated space. If size is 0, either a null pointer or a unique pointer that can be successfully 

21958 cx passed to free( ) shall be returned. Otherwise, it shall return a null pointer and set errno to 

21959 indicate the error. 

21960 ERRORS 

21961 The malloc() function shall fail if: 

21962 cx [ENOMEM] Insufficient storage space is available. 

21963 EXAMPLES 

21964 None. 

21965 APPLICATION USAGE 

21966 None. 

21967 RATIONALE 

21968 None. 

21969 FUTURE DIRECTIONS 

21970 None. 

21971 SEE ALSO 

21972 callocO, freeOr realloc Or the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

21973 <stdlib.h> 

21974 CHANGE HISTORY 

21975 First released in Issue 1. 

21976 Derived from Issue 1 of the SVID. 
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21977 Issue 4 

21978 

21979 

21980 

21981 

21982 

21983 Issue 6 

21984 

21985 

21986 

21987 

21988 


The setting of errno and the [ENOMEM] error are marked as extensions. 

The APPLICATION USAGE section is changed to record that <malloc.h> need no longer be 
supported on XSI-conformant systems. 

The following change is incorporated for alignment with the ISO C standard: 

• The RETURN VALUE section is updated to indicate what is returned if size is 0. 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the RETURN VALUE section, the requirement to set errno to indicate an error is added. 

• The [ENOMEM] error condition is added. 
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21989 NAME 

21990 mblen — get number of bytes in a character 

21991 SYNOPSIS 

21992 #include <stdlib.h> 

21993 int mblen (const char *s, size_t n) ; 

21994 DESCRIPTION 

21995 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

21996 conflict between the requirements described here and the ISO C standard is unintentional. This I 

21997 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

21998 If s is not a null pointer, mblen() determines the number of bytes constituting the character 

21999 pointed to by s. Except that the shift state of mbtowc{ ) is not affected, it is equivalent to: 

22000 mbtowc ( (wchar_t *)0, s, n) ; 

22001 The implementation shall behave as if no function defined in this volume of 

22002 IEEE Std. 1003.1-200x calls mblen (). 

22003 The behavior of this function is affected by the LC_CTYPE category of the current locale. For a 

22004 state-dependent encoding, this function is placed into its initial state by a call for which its 

22005 character pointer argument, s, is a null pointer. Subsequent calls with s as other than a null 

22006 pointer cause the internal state of the function to be altered as necessary. A call with s as a null 

22007 pointer causes this function to return a non-zero value if encodings have state dependency, and 

22008 0 otherwise. If the implementation employs special bytes to change the shift state, these bytes do 

22009 not produce separate wide-character codes, but are grouped with an adjacent character. 

22010 Changing the LCJCTYPE category causes the shift state of this function to be indeterminate. 

22011 RETURN VALUE 

22012 If s is a null pointer, mblen() shall return a non-zero or 0 value, if character encodings, 

22013 respectively, do or do not have state-dependent encodings. If s is not a null pointer, mblen () shall 

22014 either return 0 (if s points to the null byte), or return the number of bytes that constitute the 

22015 character (if the next n or fewer bytes form a valid character), or return -1 (if they do not form a 

22016 cx valid character) and may set errno to indicate the error. In no case shall the value returned be 

22017 greater than n or the value of the {MB_CUR_MAX} macro. 

22018 ERRORS 

22019 The rnbleni ) function may fail if: 

22020 xsi [EILSEQ] Invalid character sequence is detected. 

22021 EXAMPLES 

22022 None. 

22023 APPLICATION USAGE 

22024 None. 

22025 RATIONALE 

22026 None. 

22027 FUTURE DIRECTIONS 

22028 None. 

22029 SEE ALSO 

22030 mbtowc (), mbstowcs (), wctomb(), wcstombs(), the System Interface Definitions volume of 

22031 IEEE Std. 1003.1-200x, <stdlib.h> 
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22032 

22033 

22034 


CHANGE HISTORY 

First released in Issue 4. 

Aligned with the ISO C standard. 
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22035 NAME 

22036 mbrlen — get number of bytes in a character (restartable) 

22037 SYNOPSIS 

22038 tinclude <wchar.h> 


22039 size_t mbrlen (const char *s, size_t n, mbstate_t *ps); 


22040 DESCRIPTION 

22041 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

22042 conflict between the requirements described here and the ISO C standard is unintentional. This I 

22043 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

22044 If s is not a null pointer, mbrlen () shall determine the number of bytes constituting the character 

22045 pointed to by s. It is equivalent to: 

22046 mbstate_t internal; 

22047 mbrtowc (NULL, s, n, ps != NULL ? ps : Sinternal); 


22048 If ps is a null pointer, the mbrlen() function uses its own internal mbstate_t object, which is I 

22049 initialized at program start-up to the initial conversion state. Otherwise, the mbstate_t object I 

22050 pointed to by ps is used to completely describe the current conversion state of the associated 

22051 character sequence. The implementation shall behave as if no function defined in this volume of 

22052 IEEE Std. 1003.1-200x calls mbrlen(). 

22053 xsi The behavior of this function is affected by the LCJCTYPE category of the current locale. 


22054 RETURN VALUE 

22055 The mbrlen () function shall return the first of the following that applies: 

22056 0 If the next n or fewer bytes complete the character that corresponds to the null 

22057 wide character. 


22058 positive If the next n or fewer bytes complete a valid character; the value returned shall 

22059 be the number of bytes that complete the character. 


22060 

22061 

22062 

22063 

22064 


(size_t)-2 If the next n bytes contribute to an incomplete but potentially valid character, 

and all n bytes have been processed. When n has at least the value of the 
{MB_CUR_MAX} macro, this case can only occur if s points at a sequence of 
redundant shift sequences (for implementations with state-dependent 
encodings). 


22065 

22066 
22067 


(size_t)-l If an encoding error occurs, in which case the next n or fewer bytes do not 

contribute to a complete and valid character. In this case, [EILSEQ] shall be 
stored in errno and the conversion state is undefined. 


22068 ERRORS 

22069 The mbrlen () function may fail if: 


22070 [EINVAL] ps points to an object that contains an invalid conversion state. 

22071 [EILSEQ] Invalid character sequence is detected. 
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22072 EXAMPLES 

22073 None. 

22074 APPLICATION USAGE 

22075 None. 

22076 RATIONALE 

22077 None. 

22078 FUTURE DIRECTIONS 

22079 None. 

22080 SEE ALSO 

22081 mbsinit(), mbrtoivc(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

22082 <wchar.h> 

22083 CHANGE HISTORY 

22084 First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 

22085 (E). I 
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22086 NAME 

22087 mbrtowc — convert a character to a wide-character code (restartable) 

22088 SYNOPSIS 

22089 tinclude <wchar.h> 


22090 size_t mbrtowc (wchar_t *pwc, const char *s, size_t n, mbstate_t *ps) ; 


22091 DESCRIPTION 

22092 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

22093 conflict between the requirements described here and the ISO C standard is unintentional. This I 

22094 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

22095 If s is a null pointer, the mbrtozvc () function shall be equivalent to the call: 


22096 mbrtowc (NULL, 1, ps) 

22097 In this case, the values of the arguments pzvc and n are ignored. 

22098 If s is not a null pointer, the mbrtozvc() function inspects at most n bytes beginning at the byte 

22099 pointed to by s to determine the number of bytes needed to complete the next character 

22100 (including any shift sequences). If the function determines that the next character is completed, it 

22101 determines the value of the corresponding wide character and then, if pzvc is not a null pointer, 

22102 stores that value in the object pointed to by pzvc. If the corresponding wide character is the null 

22103 wide character, the resulting state described is the initial conversion state. 

22104 If ps is a null pointer, the mbrtozvc() function uses its own internal mbstate_t object, which is I 

22105 initialized at program start-up to the initial conversion state. Otherwise, the mbstate_t object I 

22106 pointed to by ps is used to completely describe the current conversion state of the associated 

22107 character sequence. The implementation shall behave as if no function defined in this volume of 

22108 IEEE Std. 1003.1-200x calls mbrtozvc( ). 

22109 xsi The behavior of this function is affected by the LCJCTYPE category of the current locale. 


22110 RETURN VALUE 

22111 The mbrtozvc {) function shall return the first of the following that applies: 


22112 0 If the next n or fewer bytes complete the character that corresponds to the null 

22113 wide character (which is the value stored). 


22114 positive 

22115 

22116 


If the next n or fewer bytes complete a valid character (which is the value 
stored); the value returned shall be the number of bytes that complete the 
character. 


22117 

22118 

22119 

22120 
22121 


(size_t)-2 If the next n bytes contribute to an incomplete but potentially valid character, 

and all n bytes have been processed (no value is stored). When n has at least 
the value of the {MB_CUR_MAX} macro, this case can only occur if s points at 
a sequence of redundant shift sequences (for implementations with state- 
dependent encodings). 


22122 

22123 

22124 


(size_t)-l If an encoding error occurs, in which case the next n or fewer bytes do not 

contribute to a complete and valid character (no value is stored). In this case, 
[EILSEQ] shall be stored in errno and the conversion state is undefined. 


22125 ERRORS 

22126 The mbrtozvc () function may fail if: 

22127 cx [EINVAL] ps points to an object that contains an invalid conversion state. 

22128 [EILSEQ] Invalid character sequence is detected. 
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22129 EXAMPLES 

22130 None. 

22131 APPLICATION USAGE 

22132 None. 

22133 RATIONALE 

22134 None. 

22135 FUTURE DIRECTIONS 

22136 None. 

22137 SEE ALSO 

22138 mbsinit(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

22139 CHANGE HISTORY 

22140 First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 

22141 (E). I 
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22142 

22143 

22144 

22145 

22146 

22147 

22148 

22149 

22150 

22151 

22152 

22153 

22154 

22155 

22156 

22157 

22158 

22159 

22160 

22161 

22162 

22163 

22164 

22165 

22166 

22167 

22168 

22169 

22170 

22171 

22172 

22173 

22174 

22175 

22176 

22177 

22178 

22179 

22180 


NAME 

mbsinit — determine conversion object status 

SYNOPSIS 

#include <wchar.h> 

int mbsinit(const mbstate_t *ps ); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

If ps is not a null pointer, the mbsinit () function shall determine whether the object pointed to by 
ps describes an initial conversion state. 

RETURN VALUE 

The mbsinit () function shall return non-zero if ps is a null pointer, or if the pointed-to object 
describes an initial conversion state; otherwise, it shall return zero. 

If an mbstate_t object is altered by any of the functions described as "restartable", and is then 
used with a different character sequence, or in the other conversion direction, or with a different 
LC_CTYPE category setting than on earlier function calls, the behavior is undefined. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

The mbstate_t object is used to describe the current conversion state from a particular character 
sequence to a wide-character sequence (or vice versa) under the rules of a particular setting of the 
LCJCTYPE category of the current locale. 

The initial conversion state corresponds, for a conversion in either direction, to the beginning of 
a new character sequence in the initial shift state. A zero valued mbstate_t object is at least one 
way to describe an initial conversion state. A zero valued mbstate_t object can be used to initiate 
conversion involving any character sequence, in any LC_CTYPE category setting. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

mbrleni ), mbrtowc(), wcrtomb(), mbsrtozvcs(), wcsrtombs (), the System Interface Definitions 
volume of IEEE Std. 1003.1-200x, <wchar.h> 

CHANGE HISTORY 

First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 
(E). I 
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22181 NAME 

22182 mbsrtowcs — convert a character string to a wide-character string (restartable) 

22183 SYNOPSIS 

22184 #include <wchar.h> 

22185 size_t mbsrtowcs (wchar_t *dst, const char **src, size_t len, 

22186 mbstate_t *ps) ; 

22187 DESCRIPTION 

22188 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

22189 conflict between the requirements described here and the ISO C standard is unintentional. This I 

22190 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

22191 The mbsrtowcs() function shall convert a sequence of characters, beginning in the conversion 

22192 state described by the object pointed to by ps, from the array indirectly pointed to by src into a 

22193 sequence of corresponding wide characters. If dst is not a null pointer, the converted characters 

22194 are stored into the array pointed to by dst. Conversion continues up to and including a 

22195 terminating null character, which is also stored. Conversion stops early in either of the following 

22196 cases: 

22197 • A sequence of bytes is encountered that does not form a valid character. 

22198 • len codes have been stored into the array pointed to by dst (and dst is not a null pointer). 

22199 Each conversion takes place as if by a call to the mbrtozvc( ) function. 

22200 If dst is not a null pointer, the pointer object pointed to by src is assigned either a null pointer (if 

22201 conversion stopped due to reaching a terminating null character) or the address just past the last 

22202 character converted (if any). If conversion stopped due to reaching a terminating null character, 

22203 and if dst is not a null pointer, the resulting state described is the initial conversion state. 

22204 If ps is a null pointer, the mbsrtowcs{ ) function uses its own internal mbstate_t object, which is I 

22205 initialized at program start-up to the initial conversion state. Otherwise, the mbstate_t object I 

22206 pointed to by ps is used to completely describe the current conversion state of the associated 

22207 character sequence. The implementation behaves as if no function defined in this volume of 

22208 IEEE Std. 1003.1-200x calls mbsrtozvcs( ). 

22209 xsi The behavior of this function shall be affected by the LC_CTYPE category of the current locale. 

22210 RETURN VALUE 

22211 If the input conversion encounters a sequence of bytes that do not form a valid character, an 

22212 encoding error occurs. In this case, the mbsrtowcsO function stores the value of the macro 

22213 [EILSEQ] in errno and shall return (size_t)-l; the conversion state is undefined. Otherwise, it 

22214 shall return the number of characters successfully converted, not including the terminating null 

22215 (if any). 

22216 ERRORS 

22217 The mbsrtowcs( ) function may fail if: 

22218 [EINVAL] ps points to an object that contains an invalid conversion state. 

22219 [EILSEQ] Invalid character sequence is detected. 
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22220 EXAMPLES 

22221 None. 

22222 APPLICATION USAGE 

22223 None. 

22224 RATIONALE 

22225 None. 

22226 FUTURE DIRECTIONS 

22227 None. 

22228 SEE ALSO 

22229 mbsinit(), mbrtoivc(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

22230 <wchar.h> 

22231 CHANGE HISTORY 

22232 First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 

22233 (E). I 
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22234 NAME 

22235 mbstowcs — convert a character string to a wide-character string 

22236 SYNOPSIS 

22237 #include <stdlib.h> 

22238 size_t mbstowcs (wchar_t *pwcs, const char *s, size_t n) ; 

22239 DESCRIPTION 

22240 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

22241 conflict between the requirements described here and the ISO C standard is unintentional. This I 

22242 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

22243 The mbstowcs() function shall convert a sequence of characters that begins in the initial shift 

22244 state from the array pointed to by s into a sequence of corresponding wide-character codes and 

22245 stores not more than n wide-character codes into the array pointed to by pzvcs. No characters 

22246 that follow a null byte (which is converted into a wide-character code with value 0) shall be 

22247 examined or converted. Each character is converted as if by a call to mbtozvcO, except that the 

22248 shift state of mbtowc( ) is not affected. 

22249 No more than n elements shall be modified in the array pointed to by pzvcs . If copying takes 

22250 place between objects that overlap, the behavior is undefined. 

22251 xsi The behavior of this function shall be affected by the LC_CTYPE category of the current locale. If 

22252 pzvcs is a null pointer, mbstowcsO shall return the length required to convert the entire array 

22253 regardless of the value of n , but no values are stored. 

22254 RETURN VALUE 

22255 cx If an invalid character is encountered, mbstozvcsO shall return (size_t)-l and may set errno to 

22256 indicate the error. Otherwise, mbstozvcsO shall return the number of the array elements modified 

22257 (or required if pzvcs is null), not including a terminating 0 code, if any. The array shall not be 

22258 zero-terminated if the value returned is n. 

22259 ERRORS 

22260 The mbstozvcs( ) function may fail if: 

22261 xsi [EILSEQ] Invalid byte sequence is detected. 

22262 EXAMPLES 

22263 None. 

22264 APPLICATION USAGE 

22265 None. 

22266 RATIONALE 

22267 None. 

22268 FUTURE DIRECTIONS 

22269 None. 

22270 SEE ALSO 

22271 mblenOf mbtowcO , zvctovibO, zvcstombs(), the System Interface Definitions volume of 

22272 IEEE Std. 1003.1-200x, <stdlib.h> 

22273 CHANGE HISTORY 

22274 First released in Issue 4. 

22275 Aligned with the ISO C standard. 
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22276 NAME 

22277 mbtowc — convert a character to a wide-character code 

22278 SYNOPSIS 

22279 #include <stdlib.h> 

22280 int mbtowc (wchar_t *pwc, const char *s, size_t n) ; 

22281 DESCRIPTION 

22282 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

22283 conflict between the requirements described here and the ISO C standard is unintentional. This I 

22284 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

22285 If s is not a null pointer, mbtowc () shall determine the number of the bytes that constitute the 

22286 character pointed to by s. It then determines the wide-character code for the value of type 

22287 wchar_t that corresponds to that character. (The value of the wide-character code corresponding 

22288 to the null byte is 0.) If the character is valid and pzvc is not a null pointer, mbtowc( ) stores the 

22289 wide-character code in the object pointed to by pzvc. 

22290 The behavior of this function is affected by the LCJCTYPE category of the current locale. For a 

22291 state-dependent encoding, this function is placed into its initial state by a call for which its 

22292 character pointer argument, s, is a null pointer. Subsequent calls with s as other than a null 

22293 pointer cause the internal state of the function to be altered as necessary. A call with s as a null 

22294 pointer causes this function to return a non-zero value if encodings have state dependency, and 

22295 0 otherwise. If the implementation employs special bytes to change the shift state, these bytes do 

22296 not produce separate wide-character codes, but are grouped with an adjacent character. 

22297 Changing the LC_CTYPE category causes the shift state of this function to be indeterminate. At 

22298 most n bytes of the array pointed to by s shall be examined. 

22299 The implementation shall behave as if no function defined in this volume of 

22300 IEEE Std. 1003.1-200x calls mbtozvc( ). 

22301 RETURN VALUE 

22302 If s is a null pointer, mbtozvc() shall return a non-zero or 0 value, if character encodings, 

22303 respectively, do or do not have state-dependent encodings. If s is not a null pointer, mbtozvc() 

22304 shall either return 0 (if s points to the null byte), or return the number of bytes that constitute the 

22305 cx converted character (if the next n or fewer bytes form a valid character), or return -1 and may 

22306 set errno to indicate the error (if they do not form a valid character). 

22307 In no case shall the value returned be greater than n or the value of the {MB_CUR_MAX[ macro. 

22308 ERRORS 

22309 The mbtowc ( ) function may fail if: 

22310 xsi [EILSEQ] Invalid character sequence is detected. 

22311 EXAMPLES 

22312 None. 

22313 APPLICATION USAGE 

22314 None. 

22315 RATIONALE 

22316 None. 

22317 FUTURE DIRECTIONS 

22318 None. 
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22319 SEE ALSO 

22320 mb ten (), mbstoivcs(), zvctomb(), wcstombs(), the System Interface Definitions volume of 

22321 IEEE Std. 1003.1-200x, <stdlib.h> 

22322 CHANGE HISTORY 

22323 First released in Issue 4. 

22324 Aligned with the ISO C standard. 
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22325 NAME 

22326 memccpy — copy bytes in memory 

22327 SYNOPSIS 

22328 xsi #include <string.h> 

22329 void *memccpy (void *sl, const void *s2, int c, size_t n) ; 

22330 

22331 DESCRIPTION 

22332 The memccpyO function shall copy bytes from memory area s2 into si, stopping after the first 

22333 occurrence of byte c (converted to an unsigned char) is copied, or after n bytes are copied, 

22334 whichever comes first. If copying takes place between objects that overlap, the behavior is 

22335 undefined. 

22336 RETURN VALUE 

22337 The memccpyO function shall return a pointer to the byte after the copy of c in si, or a null 

22338 pointer if c was not found in the first n bytes of s2. 

22339 ERRORS 

22340 No errors are defined. 

22341 EXAMPLES 

22342 None. 

22343 APPLICATION USAGE 

22344 The memccpy ( ) function does not check for the overflow of the receiving memory area. 

22345 RATIONALE 

22346 None. 

22347 FUTURE DIRECTIONS 

22348 None. 

22349 SEE ALSO 

22350 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

22351 CHANGE HISTORY 

22352 First released in Issue 1. 

22353 Derived from Issue 1 of the SVID. 

22354 Issue 4 

22355 The type of argument s2 is changed from void* to const void*. 

22356 Reference to use of the <memory.h> header is removed from the APPLICATION USAGE 

22357 section. 

22358 The FUTURE DIRECTIONS section is removed. 
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22359 NAME 

22360 memchr — find byte in memory 

22361 SYNOPSIS 

22362 #include <string.h> 

22363 void *memchr (const void *s, int c, size_t n) ; 

22364 DESCRIPTION 

22365 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

22366 conflict between the requirements described here and the ISO C standard is unintentional. This I 

22367 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

22368 The memchr ( ) function shall locate the first occurrence of c (converted to an unsigned char) in 

22369 the initial n bytes (each interpreted as unsigned char) of the object pointed to by s . 

22370 RETURN VALUE 

22371 The memchr ( ) function shall return a pointer to the located byte, or a null pointer if the byte does 

22372 not occur in the object. 

22373 ERRORS 

22374 No errors are defined. 

22375 EXAMPLES 

22376 None. 

22377 APPLICATION USAGE 

22378 None. 

22379 RATIONALE 

22380 None. 

22381 FUTURE DIRECTIONS 

22382 None. 

22383 SEE ALSO 

22384 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

22385 CHANGE HISTORY 

22386 First released in Issue 1. 

22387 Derived from Issue 1 of the SVID. 

22388 Issue 4 

22389 The APPLICATION USAGE section is removed. 

22390 The following changes are incorporated for alignment with the ISO C standard: 

22391 • The function is no longer marked as an extension. 

22392 • The type of argument s is changed from void 51 ' to const void 51 '. 
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22393 

22394 

22395 

22396 

22397 

22398 

22399 

22400 

22401 

22402 

22403 

22404 

22405 

22406 

22407 

22408 

22409 

22410 

22411 

22412 

22413 

22414 

22415 

22416 

22417 

22418 

22419 

22420 

22421 

22422 

22423 

22424 

22425 

22426 

22427 

22428 

22429 

22430 


NAME 

memcmp — compare bytes in memory 

SYNOPSIS 

#include <string.h> 

int memcmp(const void *sl, const void *s2, size_t n ); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The memcmp () function shall compare the first n bytes (each interpreted as unsigned char) of the 
object pointed to by si to the first n bytes of the object pointed to by s2. 

The sign of a non-zero return value shall be determined by the sign of the difference between the 
values of the first pair of bytes (both interpreted as type unsigned char) that differ in the objects 
being compared. 

RETURN VALUE 

The memcmpO function shall return an integer greater than, equal to, or less than 0, if the object 
pointed to by si is greater than, equal to, or less than the object pointed to by s2, respectively. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

The System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The RETURN VALUE section is clarified. 

The APPLICATION USAGE section is removed. 

The following changes are incorporated for alignment with the ISO C standard: 

• The function is no longer marked as an extension. 

• The type of arguments si and s2 are changed from void 51 ' to const void 51 '. 
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22431 NAME 

22432 memcpy — copy bytes in memory 

22433 SYNOPSIS 

22434 #include <string.h> 

22435 void *memcpy (void *sl, const void *s2, size_t n) ; 

22436 DESCRIPTION 

22437 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

22438 conflict between the requirements described here and the ISO C standard is unintentional. This I 

22439 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

22440 The memcpy( ) function shall copy n bytes from the object pointed to by s2 into the object pointed 

22441 to by si. If copying takes place between objects that overlap, the behavior is undefined. 

22442 RETURN VALUE 

22443 The memcpy () function shall return si ; no return value is reserved to indicate an error. 

22444 ERRORS 

22445 No errors are defined. 

22446 EXAMPLES 

22447 None. 

22448 APPLICATION USAGE 

22449 The memcpy () function does not check for the overflowing of the receiving memory area. 

22450 RATIONALE 

22451 None. 

22452 FUTURE DIRECTIONS 

22453 None. 

22454 SEE ALSO 

22455 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

22456 CHANGE HISTORY 

22457 First released in Issue 1. 

22458 Derived from Issue 1 of the SVID. 

22459 Issue 4 

22460 Reference to use of the <memory.h> header is removed from the APPLICATION USAGE 

22461 section, and a note about overflow checking has been added. 

22462 The FUTURE DIRECTIONS section is removed. 

22463 The following changes are incorporated for alignment with the ISO C standard: 

22464 • The function is no longer marked as an extension. 

22465 • The type of argument s2 is changed from void* to const void*. 
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22466 NAME 

22467 memmove — copy bytes in memory with overlapping areas 

22468 SYNOPSIS 

22469 tinclude <string.h> 

22470 void *memmove (void *sl, const void *s2, size_t n) ; 

22471 DESCRIPTION 

22472 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

22473 conflict between the requirements described here and the ISO C standard is unintentional. This I 

22474 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

22475 The memmove() function shall copy n bytes from the object pointed to by s2 into the object 

22476 pointed to by si . Copying takes place as if the n bytes from the object pointed to by s2 are first 

22477 copied into a temporary array of n bytes that does not overlap the objects pointed to by si and 

22478 s2, and then the n bytes from the temporary array are copied into the object pointed to by si. 

22479 RETURN VALUE 

22480 The memmove () function shall return si ; no return value is reserved to indicate an error. 

22481 ERRORS 

22482 No errors are defined. 

22483 EXAMPLES 

22484 None. 

22485 APPLICATION USAGE 

22486 None. 

22487 RATIONALE 

22488 None. 

22489 FUTURE DIRECTIONS 

22490 None. 

22491 SEE ALSO 

22492 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

22493 CHANGE HISTORY 

22494 First released in Issue 4. 

22495 Derived from the ANSI C standard. 


716 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


memsetO 


22496 NAME 

22497 memset — set bytes in memory 

22498 SYNOPSIS 

22499 tinclude <string.h> 

22500 void *memset (void *s, int c, size_t n) ; 

22501 DESCRIPTION 

22502 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

22503 conflict between the requirements described here and the ISO C standard is unintentional. This I 

22504 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

22505 The memset ( ) function shall copy c (converted to an unsigned char) into each of the first n bytes 

22506 of the object pointed to by s. 

22507 RETURN VALUE 

22508 The memset () function shall return s; no return value is reserved to indicate an error. 

22509 ERRORS 

22510 No errors are defined. 

22511 EXAMPLES 

22512 None. 

22513 APPLICATION USAGE 

22514 None. 

22515 RATIONALE 

22516 None. 

22517 FUTURE DIRECTIONS 

22518 None. 

22519 SEE ALSO 

22520 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

22521 CHANGE HISTORY 

22522 First released in Issue 1. 

22523 Derived from Issue 1 of the SVID. 

22524 Issue 4 

22525 The APPLICATION USAGE section is removed. 

22526 The following change is incorporated for alignment with the ISO C standard: 

22527 • The function is no longer marked as an extension. 
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NAME 

mkdir — make a directory 

SYNOPSIS 

#include <sys/stat.h> 


int mkdir(const char *path, mode_t mode); 

DESCRIPTION 

The mkdir () function creates a new directory with name path . The file permission bits of the new 
directory are initialized from mode. These file permission bits of the mode argument are modified 
by the process' file creation mask. 

When bits in mode other than the file permission bits are set, the meaning of these additional bits 
is implementation-dependent. 

The directory's user ID is set to the process' effective user ID. The directory's group ID shall be 
set to the group ID of the parent directory or to the effective group ID of the process. 

The newly created directory shall be an empty directory. 

If path names a symbolic link, mkdir () shall fail and set errno to [EEXIST]. I 

Upon successful completion, mkdir () shall mark for update the st_atime, st_ctime, and st_mtime I 
fields of the directory. Also, the st_ctime and st_mtime fields of the directory that contains the 
new entry shall be marked for update. 

RETURN VALUE 

Upon successful completion, mkdir () shall return 0. Otherwise, -1 shall be returned, no directory 
shall be created, and errno shall be set to indicate the error. 


ERRORS 

The mkdir () function shall fail if: 


MAN 


[EACCES] Search permission is denied on a component of the path prefix, or write 

permission is denied on the parent directory of the directory to be created. 

[EEXIST] The named file exists. 

[ELOOP] A loop exists in symbolic links encountered during resolution of the path I 

argument. I 

[EMLINK] The link count of the parent directory would exceed jLINK_MAX[. 

[ENAMETOOLONG] 

The length of the path argument exceeds {PATH_MAX[ or a path name 
component is longer than {NAME_MAX[ while _POSIX_NO_TRUNC is in 
effect. 


[ENOENT] 

[ENOSPC] 

[ENOTDIR] 

[EROFS] 


A component of the path prefix specified by path does not name an existing 
directory or path is an empty string. 

The file system does not contain enough space to hold the contents of the new 
directory or to extend the parent directory of the new directory. 

A component of the path prefix is not a directory. 

The parent directory resides on a read-only file system. 


The mkdir () function may fail if: 


[ELOOP] More than [SYMLOOP_MAX[ symbolic links were encountered during I 

resolution of the path argument. I 
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22609 


MAN [ENAMETOOLONG] 

As a result of encountering a symbolic link in resolution of the path argument, I 
the length of the substituted path name string exceeded {PATH_MAX}. I 

EXAMPLES 

Creating a Directory 

The following example shows how to create a directory named /home/cnd/modl, with 
read/write /search permissions for owner and group, and with read/search permissions for 
others. 

#include <sys/types.h> 

#include <sys/stat.h> 

int status; 

status = mkdir("/home/cnd/modl", S_IRWXU | S_IRWXG I S_IROTH | S_IXOTH); 

APPLICATION USAGE 

None. 

RATIONALE 

The mkdir () function originated in 4.2 BSD and was added to System V in Release 3.0. 

4.3 BSD detects [ENAMETOOLONG]. 

See getgroups () about the group of a newly created directory. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

umask(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, <sys/stat.h>, 
<sys/types.h> 

CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the POSIX.1-1988 standard. 

Issue 4 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 
XSI-conformant systems. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The type of argument path is changed from char* to const char*. 

The following changes are incorporated for alignment with the FIPS requirements: 

• In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 
name component is larger than [NAME_MAX[ is now defined as mandatory and marked as 
an extension. 

Issue 4, Version 2 

The ERRORS section is updated for X/OPEN UNIX conformance as follows: 

• It states that [ELOOP] is returned if too many symbolic links are encountered during path 
name resolution. 
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• A second [ENAMETOOLONG] condition is defined that may report excessive length of an 
intermediate result of path name resolution of a symbolic link. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 
This is since behavior may vary from one file system to another. 

The following new requirements on POSIX implementations derive from alignment with the 

Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• The [ELOOP] mandatory error condition is added. 

• A second [ENAMETOOLONG] is added as an optional error condition. 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• The [ELOOP] optional error condition is added. 
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22626 NAME 

22627 mkfifo — make a FIFO special file 

22628 SYNOPSIS 

22629 #include <sys/stat.h> 


22630 int mkfifo (const char *path, mode_t mode); 

22631 DESCRIPTION 

22632 The mkfifo () function shall create a new FIFO special file named by the path name pointed to by 

22633 path. The file permission bits of the new FIFO are initialized from mode. The file permission bits 

22634 of the mode argument are modified by the process' file creation mask. 

22635 When bits in mode other than the file permission bits are set, the effect is implementation- 

22636 dependent. 

22637 If path names a symbolic link, nikdir () shall fail and set errno to [EEXIST]. I 

22638 The FIFO's user ID shall be set to the process' effective user ID. The FIFO's group ID is set to the I 

22639 group ID of the parent directory or to the effective group ID of the process. 

22640 Upon successful completion, mkfifo () shall mark for update the st_atime, stjctime, and st_mtime 

22641 fields of the file. Also, the stjctime and st_mtime fields of the directory that contains the new 

22642 entry shall be marked for update. 

22643 RETURN VALUE 

22644 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned, no FIFO shall 

22645 be created, and errno shall be set to indicate the error. 


22646 ERRORS 

22647 The mkfifo () function shall fail if: 


22648 

22649 


[EACCES] A component of the path prefix denies search permission, or write permission 

is denied on the parent directory of the FIFO to be created. 


22650 [EEXIST] 

22651 MAN [ELOOP] 

22652 


The named file already exists. 

A loop exists in symbolic links encountered during resolution of the path I 
argument. I 


22653 

22654 

22655 

22656 


[ENAMETOOLONG] 

The length of the path argument exceeds {PATH_MAX} or a path name 
component is longer than {NAME_MAX[ while _POSIX_NO_TRUNC is in 
effect. 


22657 

22658 


[ENOENT] A component of the path prefix specified by path does not name an existing 

directory or path is an empty string. 


22659 

22660 


[ENOSPC] The directory that would contain the new file cannot be extended or the file 

system is out of file-allocation resources. 


22661 

22662 

22663 


[ENOTDIR] A component of the path prefix is not a directory. 
[EROFS] The named file resides on a read-only file system. 

The mkfifo () function may fail if: 


22664 [ELOOP] More than [SYMLOOP_MAX[ symbolic links were encountered during I 

22665 resolution of the path argument. I 

22666 MAN 

22667 


[ENAMETOOLONG] 

As a result of encountering a symbolic link in resolution of the path argument. 
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22668 

22669 

22670 

22671 

22672 

22673 

22674 

22675 

22676 

22677 

22678 

22679 

22680 

22681 

22682 

22683 

22684 

22685 

22686 

22687 

22688 

22689 

22690 

22691 

22692 

22693 

22694 

22695 

22696 

22697 

22698 

22699 

22700 

22701 

22702 

22703 

22704 

22705 

22706 

22707 


the length of the substituted path name string exceeded |PATH_MAX}. 

EXAMPLES 

Creating a FIFO File 

The following example shows how to create a FIFO file named /home/cnd/mod_done, with 
read/write permissions for owner, and with read permissions for group and others. 

tinclude <sys/types.h> 
tinclude <sys/stat.h> 

int status; 

status = mkfifo("/home/cnd/mod_done", S_IWUSR | S_IRUSR | 

S_IRGRP | S_IROTH); 

APPLICATION USAGE 

None. 

RATIONALE 

The syntax of this function is intended to maintain compatibility with historical 
implementations of mknod(). The latter function was included in the 1984 /usr/group standard 
but only for use in creating FIFO special files. The mknod() function was originally excluded 
from the POSIX.1-1988 standard as implementation-dependent and replaced by mkdir() and 
mkfifo(). The mknod() function is now included for alignment with the Single UNIX 
Specification. 

See getgroups () about the group of a newly created FIFO. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

umaski ), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <sys/stat.h>, 
<sys/types.h> 

CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the POSIX.1-1988 standard. 

Issue 4 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 
XSI-conformant systems. 

The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

• The type of argument path is changed from char* to const char*. 

• The description of [EACCES] is updated to indicate that this error is also returned if write 
permission is denied to the parent directory. 

The following changes are incorporated for alignment with the FIPS requirements: 

• In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 
name component is larger that |NAME_MAX} is now defined as mandatory and marked as 
an extension. 
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22708 

22709 

22710 

22711 

22712 

22713 

22714 

22715 

22716 

22717 

22718 

22719 

22720 

22721 

22722 

22723 

22724 

22725 

22726 

22727 


Issue 4, Version 2 

The ERRORS section is updated for X/OPEN UNIX conformance as follows: 

• It states that [ELOOP] is returned if too many symbolic links are encountered during path 
name resolution. 

• A second [ENAMETOOLONG] condition is defined that may report excessive length of an 
intermediate result of path name resolution of a symbolic link. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 
This is since behavior may vary from one file system to another. 

The following new requirements on POSIX implementations derive from alignment with the 

Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• The [ELOOP] mandatory error condition is added. 

• A second [ENAMETOOLONG] is added as an optional error condition. 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• The [ELOOP] optional error condition is added. 
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22728 NAME 

22729 mknod — make a directory, a special or regular file 

22730 SYNOPSIS 

22731 xsi tinclude <sys/stat.h> 

22732 int mknod (const char *path, mode_t mode, dev_t dev); 

22733 


22734 DESCRIPTION 

22735 The mknod () function shall create a new file named by the path name to which the argument 

22736 path points. 


22737 

22738 

22739 

22740 

22741 

22742 

22743 

22744 

22745 


The file type for path is OR'ed into the mode argument, and the application shall select one of the I 
following symbolic constants: I 


Name 

Description 

S_IFIFO 

S_IFCHR 

S_IFDIR 

S_IFBLK 

SJFREG 

FIFO-special 

Character-special (non-portable) 
Directory (non-portable) 
Block-special (non-portable) 
Regular (non-portable) 


22746 The only portable use of mknod () is to create a FIFO-special file. If mode is not S_IFIFO or dev is 

22747 not 0, the behavior of mknod() is unspecified. 

22748 The permissions for the new file are OR'ed into the mode argument, and may be selected from 

22749 any combination of the following symbolic constants: 

22750 


22751 

Name 

Description 

22752 

S_ISUID 

Set user ID on execution. 

22753 

S_ISGID 

Set group ID on execution. 

22754 

S_IRWXU 

Read, write, or execute (search) by owner. 

22755 

S_IRUSR 

Read by owner. 

22756 

S_IWUSR 

Write by owner. 

22757 

S_IXUSR 

Execute (search) by owner. 

22758 

S_IRWXG 

Read, write, or execute (search) by group. 

22759 

S_IRGRP 

Read by group. 

22760 

S_IWGRP 

Write by group. 

22761 

S_IXGRP 

Execute (search) by group. 

22762 

S_IRWXO 

Read, write, or execute (search) by others. 

22763 

S_IROTH 

Read by others. 

22764 

S_IWOTH 

Write by others. 

22765 

S_IXOTH 

Execute (search) by others. 

22766 

S_ISVTX 

On directories, restricted deletion flag. 


22767 The user ID of the file is initialized to the effective user ID of the process. The group ID of the file 

22768 is initialized to either the effective group ID of the process or the group ID of the parent 

22769 directory. 

22770 The owner, group, and other permission bits of mode are modified by the file mode creation 

22771 mask of the process. The mknod () function clears each bit whose corresponding bit in the file 

22772 mode creation mask of the process is set. 
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22773 

Upon successful completion, mknod() shall mark for update the st_atime, st_ctime, and st_mtime 

22774 

fields of the file. Also, the st_ctime and s t_mtime fields of the directory that contains the new 

22775 

entry shall be marked for update. 

22776 

Only a process with appropriate privileges may invoke mknod( ) for file types other than FIFO- 

22777 

special. 


22778 RETURN VALUE 


22779 

Upon successful completion, mknod () shall return 0. Otherwise, it shall return —1, the new file 

22780 

shall not be created, and errno shall be set to indicate the error. 

22781 ERRORS 


22782 

The mknod () function shall fail if: 

22783 

[EPERM] 

The invoking process does not have appropriate privileges and the file type is 

22784 


not FIFO-special. 

22785 

[ENOTDIR] 

A component of the path prefix is not a directory. 

22786 

[ENOENT] 

A component of the path prefix specified by path does not name an existing 

22787 


directory or path is an empty string. 

22788 

[EACCES] 

A component of the path prefix denies search permission, or write permission 

22789 


is denied on the parent directory. 

22790 

[EROFS] 

The directory in which the file is to be created is located on a read-only file 

22791 


system. 

22792 

[EEXIST] 

The named file exists. 

22793 

[EIO] 

An I/O error occurred while accessing the file system. 

22794 

[EINVAL] 

An invalid argument exists. 

22795 

[ENOSPC] 

The directory that would contain the new file cannot be extended or the file 

22796 


system is out of file allocation resources. 

22797 

[ELOOP] 

Too many symbolic links were encountered in resolving path. 

22798 

[ENAMETOOLONG] 

22799 


The length of a path name exceeds |PATH_MAX}, or path name component is 

22800 


longer than {NAME_MAX}. 

22801 

The mknod () function may fail if: 

22802 

[ENAMETOOLONG] 

22803 


Path name resolution of a symbolic link produced an intermediate result 

22804 


whose length exceeds {PATH_MAX}. 

22805 EXAMPLES 


22806 

Creating a FIFO Special File 

22807 

The following example shows how to create a FIFO special file named /home/cnd/mod_done. 

22808 

with read/write permissions for owner, and with read permissions for group and others. 

22809 

#include 

<sys/types.h> 

22810 

#include 

<sys/stat.h> 

22811 

dev_t dev; 

22812 

int status; 

22813 
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22814 status = mknod ("/home/cnd/mod_done", S_IFIFO I S_IWUSR | 

22815 S_IRUSR | S_IRGRP I S_IROTH, dev) ; 

22816 APPLICATION USAGE 

22817 mkfifo () is preferred over this function for making FIFO special files. 

22818 RATIONALE 

22819 None. 

22820 FUTURE DIRECTIONS 

22821 None. 

22822 SEE ALSO 

22823 chmod(), creat(), exec, mkdir(), mkfifo(), open(), stat(), umask(), the System Interface Definitions 

22824 volume of IEEE Std. 1003.1-200x, <sys/stat.h> 

22825 CHANGE HISTORY 

22826 First released in Issue 4, Version 2. 

22827 Issue 5 

22828 Moved from X/OPEN UNIX extension to BASE. 

22829 Issue 6 

22830 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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22831 NAME 

22832 mkstemp — make a unique file name 

22833 SYNOPSIS 

22834 xsi tinclude <stdlib.h> 

22835 int mkstemp (char * template) ; 

22836 

22837 DESCRIPTION 

22838 The mkstemp () function shall replace the contents of the string pointed to by template by a unique 

22839 file name, and return a file descriptor for the file open for reading and writing. The function thus 

22840 prevents any possible race condition between testing whether the file exists and opening it for 

22841 use. The string in template should look like a file name with six trailing Xs; mkstempO replaces 

22842 each X with a character from the portable file name character set. The characters are chosen such 

22843 that the resulting name does not duplicate the name of an existing file at the time of a call to 

22844 mkstempO- 

22845 RETURN VALUE 

22846 Upon successful completion, mkstemp () shall return an open file descriptor. Otherwise, -1 shall 

22847 be returned if no suitable file could be created. 

22848 ERRORS 

22849 No errors are defined. 

22850 EXAMPLES 

22851 Generating a File Name 

22852 The following example creates a file with a 10-character name beginning with the characters 

22853 "file" and opens the file for reading and writing. The value returned as the value of/d is a file 

22854 descriptor that identifies the file. 

22855 #include <stdlib.h> 

22856 

22857 char *template = "/tmp/fileXXXXXX"; 

22858 int fd; 

22859 fd = mkstemp (template); 

22860 APPLICATION USAGE 

22861 It is possible to run out of letters. 

22862 The mkstempO function need not check to determine whether the file name part of template 

22863 exceeds the maximum allowable file name length. 

22864 RATIONALE 

22865 None. 

22866 FUTURE DIRECTIONS 

22867 None. 

22868 SEE ALSO 

22869 getpidO , open (), tmpfileO , tmpnamO , the System Interface Definitions volume of 

22870 IEEE Std. 1003.1-200x, <stdlib.h> 
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22871 CHANGE HISTORY 

22872 First released in Issue 4, Version 2. 

22873 Issue 5 

22874 Moved from X/OPEN UNIX extension to BASE. 
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22875 NAME 

22876 mktemp — make a unique file name (LEGACY) 

22877 SYNOPSIS 

22878 xsi #include <stdlib.h> 

22879 char *mktemp (char * template) ; 

22880 

22881 DESCRIPTION 

22882 The mktemp () function shall replace the contents of the string pointed to by template by a unique 

22883 file name and return template. The application shall initialize template to be a file name with six 

22884 trailing Xs; mktemp ( ) shall replace each X with a single byte character from the portable file 

22885 name character set. 

22886 RETURN VALUE 

22887 The mktemp () function shall return the pointer template. If a unique name cannot be created, 

22888 template shall point to a null string. 

22889 ERRORS 

22890 No errors are defined. 

22891 EXAMPLES 

22892 Generating a File Name 

22893 The following example replaces the contents of the "template" string with a 10-character file 

22894 name beginning with the characters "file" and returns a pointer to the "template" string 

22895 that contains the new file name. 

22896 #include <stdlib.h> 

22897 

22898 char *template = "/tmp/fileXXXXXX"; 

22899 char *ptr; 

22900 ptr = mktemp (template); 

22901 APPLICATION USAGE 

22902 Between the time a path name is created and the file opened, it is possible for some other process 

22903 to create a file with the same name. The mkstempi) function avoids this problem and is preferred 

22904 over this function. 

22905 RATIONALE 

22906 None. 

22907 FUTURE DIRECTIONS 

22908 This function may be withdrawn in a future version. 

22909 SEE ALSO 

22910 mkstempi ), tmpfile(), tmpnam{), the System Interface Definitions volume of 

22911 IEEE Std. 1003.1-200x, <stdlib.h> 

22912 CHANGE HISTORY 

22913 First released in Issue 4, Version 2. 

22914 Issue 5 

22915 Moved from X/OPEN UNIX extension to BASE. 
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22916 

22917 

22918 


Issue 6 

This function is marked LEGACY. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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22919 NAME 

22920 mktime — convert broken-down time into time since the Epoch 

22921 SYNOPSIS 

22922 #include <time.h> 

22923 time_t mktime (struct tm *timeptr ); 

22924 DESCRIPTION 

22925 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

22926 conflict between the requirements described here and the ISO C standard is unintentional. This I 

22927 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

22928 The mktime () function shall convert the broken-down time, expressed as local time, in the 

22929 structure pointed to by timeptr, into a time since the Epoch value with the same encoding as that 

22930 of the values returned by time( ). The original values of the tmjwday and tm_yday components of 

22931 the structure are ignored, and the original values of the other components are not restricted to 

22932 the ranges described in <time.h>. 

22933 cx A positive or 0 value for tm_isdst shall cause mktime( ) to presume initially that Daylight Savings 

22934 Time, respectively, is or is not in effect for the specified time. A negative value for tm_isdst shall 

22935 cause mktime () to attempt to determine whether Daylight Saving Time is in effect for the 

22936 specified time. 

22937 Local timezone information shall be set as though mktime ( ) called tzset( ). 

22938 Upon successful completion, the values of the tm_wday and tmjyday components of the structure 

22939 shall be set appropriately, and the other components are set to represent the specified time since 

22940 the Epoch, but with their values forced to the ranges indicated in the <time.h> entry; the final 

22941 value of tm_mday shall not be set until tm_mon and tm_year are determined. 

22942 RETURN VALUE 

22943 The mktime () function shall return the specified time since the Epoch encoded as a value of type 

22944 time_t. If the time since the Epoch cannot be represented, the function shall return the value 

22945 (time_t)-l. 

22946 ERRORS 

22947 No errors are defined. 

22948 EXAMPLES 

22949 What day of the week is July 4,2001? 

22950 #include <stdio.h> 

22951 #include <time.h> 

22952 struct tm time_str; 

22953 char daybuf [ 2 0 ] ; 

22954 int main (void) 

22955 { 

22956 time_str. tm_year = 2001 — 1900; 

22957 time_str . tm_mon = 7 — 1; 

22958 time_str . tm_mday = 4; 

22959 time_str . tm_hour = 0; 

22960 time_str . tm_min = 0; 

22961 time_str . tm_sec = 1; 

22962 time_str . tm_isdst = —1; 

22963 if (mktime (&time_str) == -1) 
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22964 

22965 

22966 

22967 

22968 

22969 

22970 

22971 

22972 

22973 

22974 

22975 

22976 

22977 

22978 

22979 

22980 

22981 

22982 

22983 

22984 

22985 

22986 

22987 

22988 

22989 


(void)puts("-unknown-") ; 
else { 

(void)strftime(daybuf, sizeof(daybuf) , "%A", &time_str); 

(void)puts(daybuf) ; 

} 

return 0; 

} 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

asctime (), clock(), ctime(), cliff time (), gmtime (), localtime(), strftime(), strptime (), time(), ntime{), 
the System Interface Definitions volume of IEEE Std. 1003.1-200x, <time.h> 

CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the POSIX.1-1988 standard and the ANSI C standard. 

Issue 4 

In the DESCRIPTION, a paragraph is added indicating the possible settings of tm_isdst, and 
reference to setting of tm_sec for leap seconds or double leap seconds is removed (although this 
functionality is still supported). 

In the EXAMPLES section, the sample code is updated to use ISO C standard syntax. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 
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22990 NAME 

22991 mlock, munlock — lock or unlock a range of process address space (REALTIME) 

22992 SYNOPSIS 

22993 MLR #include <sys/mman.h> 

22994 int mlock (const void * addr, size_t len) ; 

22995 int munlock (const void * addr, size_t len); 

22996 

22997 DESCRIPTION 

22998 The mlock () function shall cause those whole pages containing any part of the address space of 

22999 the process starting at address addr and continuing for len bytes to be memory-resident until 

23000 unlocked or until the process exits or execs another process image. The implementation may 

23001 require that addr be a multiple of jPAGESIZE}. 

23002 The munlock() function shall unlock those whole pages containing any part of the address space 

23003 of the process starting at address addr and continuing for len bytes, regardless of how many 

23004 times mlock () has been called by the process for any of the pages in the specified range. The 

23005 implementation may require that addr be a multiple of the jPAGESIZE}. 

23006 If any of the pages in the range specified to a call to munlock( ) are also mapped into the address 

23007 spaces of other processes, any locks established on those pages by another process are 

23008 unaffected by the call of this process to munlock( ). If any of the pages in the range specified by a 

23009 call to mnnlock( ) are also mapped into other portions of the address space of the calling process 

23010 outside the range specified, any locks established on those pages via the other mappings are also 

23011 unaffected by this call. 

23012 Upon successful return from mlock (), pages in the specified range shall be locked and memory- 

23013 resident. Upon successful return from mnnlock( ), pages in the specified range shall be unlocked 

23014 with respect to the address space of the process. Memory residency of unlocked pages is 

23015 unspecified. 

23016 The appropriate privilege is required to lock process memory with mlock (). 

23017 RETURN VALUE 

23018 Upon successful completion, the mlock() and munlock() functions shall return a value of zero. 

23019 Otherwise, no change is made to any locks in the address space of the process, and the function 

23020 shall return a value of -1 and set errno to indicate the error. 

23021 ERRORS 

23022 The mlock( ) and munlock () functions shall fail if: 

23023 [ENOMEM] Some or all of the address range specified by the addr and len arguments does 

23024 not correspond to valid mapped pages in the address space of the process. 

23025 The mlock () function shall fail if: 

23026 [EAGAIN] Some or all of the memory identified by the operation could not be locked 

23027 when the call was made. 

23028 The mlock( ) and munlock( ) functions may fail if: 

23029 [EINVAL] The addr argument is not a multiple of jPAGESIZE}. 

23030 The mlock () function may fail if: 

23031 [ENOMEM] Locking the pages mapped by the specified range would exceed an 

23032 implementation-dependent limit on the amount of memory that the process 

23033 may lock. 
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23034 [EPERM] The calling process does not have the appropriate privilege to perform the 

23035 requested operation. 

23036 EXAMPLES 

23037 None. 

23038 APPLICATION USAGE 

23039 None. 

23040 RATIONALE 

23041 None. 

23042 FUTURE DIRECTIONS 

23043 None. 

23044 SEE ALSO 

23045 exec, _exit (), fork(), mlockall(), munmap(), the System Interface Definitions volume of 

23046 IEEE Std. 1003.1-200x, <sys/mman.h> 

23047 CHANGE HISTORY 

23048 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

23049 Issue 6 

23050 The mlock( ) and munlock() functions are marked as part of the _POSIX_MEMLOCK_RANGE 

23051 option. 

23052 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

23053 implementation does not support the _POSIX_MEMLOCK_RANGE option. 
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23054 

23055 

23056 

23057 

23058 

23059 

23060 

23061 

23062 

23063 

23064 

23065 

23066 

23067 

23068 

23069 

23070 

23071 

23072 

23073 

23074 

23075 

23076 

23077 

23078 

23079 

23080 

23081 

23082 

23083 

23084 

23085 

23086 

23087 

23088 

23089 

23090 

23091 

23092 

23093 

23094 

23095 

23096 

23097 

23098 

23099 


NAME 

mlockall, munlockall — lock/unlock the address space of a process (REALTIME) 
SYNOPSIS 

ml #include <sys/mman.h> 

int mlockall(int flags) ; 
int munlockall(void) ; 


DESCRIPTION 

The mlockall () function shall cause all of the pages mapped by the address space of a process to 
be memory-resident until unlocked or until the process exits or execs another process image. The 
flags argument determines whether the pages to be locked are those currently mapped by the 
address space of the process, those that are mapped in the future, or both. The flags argument is 
constructed from the bitwise-inclusive OR of one or more of the following symbolic constants, 
defined in <sys/mman.h>: 

MCL_CURRENT Lock all of the pages currently mapped into the address space of the process. 

MCL_FUTURE Lock all of the pages that become mapped into the address space of the 
process in the future, when those mappings are established. 

If MCL_FUTURE is specified, and the automatic locking of future mappings eventually causes 
the amount of locked memory to exceed the amount of available physical memory or any other 
implementation-dependent limit, the behavior is implementation-dependent. The manner in 
which the implementation informs the application of these situations is also implementation- 
dependent. 

The munlockall () function unlocks all currently mapped pages of the address space of the 
process. Any pages that become mapped into the address space of the process after a call to 
munlockall () shall not be locked, unless there is an intervening call to mlockall () specifying 
MCL_FUTURE or a subsequent call to mlockall () specifying MCL_CURRENT. If pages mapped 
into the address space of the process are also mapped into the address spaces of other processes 
and are locked by those processes, the locks established by the other processes are unaffected by 
a call by this process to munlockall (). 

Upon successful return from the mlockall () function that specifies MCL_CURRENT, all currently 
mapped pages of the process' address space shall be memory-resident and locked. Upon return 
from the munlockall () function, all currently mapped pages of the process' address space shall be 
unlocked with respect to the process' address space. The memory residency of unlocked pages is 
unspecified. 

The appropriate privilege is required to lock process memory with mlockall (). 

RETURN VALUE 

Upon successful completion, the mlockall () function shall return a value of zero. Otherwise, no 
additional memory shall be locked, and the function shall return a value of -1 and set errno to 
indicate the error. The effect of failure of mlockall () on previously existing locks in the address 
space is unspecified. 

If it is supported by the implementation, the munlockall () function shall always return a value of 
zero. Otherwise, the function shall return a value of -1 and set errno to indicate the error. 

ERRORS 

The mlockall () function shall fail if: 

[EAGAIN] Some or all of the memory identified by the operation could not be locked 

when the call was made. 
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23100 [EINVAL] Th e flags argument is zero, or includes unimplemented flags. 

23101 The vilockall () function may fail if: 

23102 [ENOMEM] 

23103 

23104 

23105 [EPERM] 

23106 

23107 EXAMPLES 

23108 None. 

23109 APPLICATION USAGE 

23110 None. 

23111 RATIONALE 

23112 None. 

23113 FUTURE DIRECTIONS 

23114 None. 

23115 SEE ALSO 

23116 exec, _exit(), fork(), mlock(), munmap(), the System Interface Definitions volume of 

23117 IEEE Std. 1003.1-200x, <sys/mman.h> 

23118 CHANGE HISTORY 

23119 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

23120 Issue 6 

23121 The vilockall () and munlockall () functions are marked as part of the _POSIX_MEMLOCK option. 

23122 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

23123 implementation does not support the _POSIX_MEMLOCK option. 


Locking all of the pages currently mapped into the address space of the 
process would exceed an implementation-dependent limit on the amount of 
memory that the process may lock. 

The calling process does not have the appropriate privilege to perform the 
requested operation. 
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23124 NAME 

23125 mmap — map pages of memory 

23126 SYNOPSIS 

23127 mfishm #include <sys/mman.h> 

23128 void *mmap (void *addr, size_t lent, int prot, int flags, 

23129 int fildes, off_t off) ; 

23130 


23131 DESCRIPTION 

23132 shm i tym The in in up ( ) function shall establish a mapping between a process' address space and a file or I 

23133 memory object. The format of the call is as follows: I 

23134 pa=mmap (addr, len, prot, flags, fildes, off); 

23135 The mmap () function establishes a mapping between the address space of the process at an 

23136 address pa for len bytes to the memory object represented by the file descriptor fildes at offset off 

23137 for len bytes. The value of pa is an implementation-dependent function of the parameter addr and 

23138 the values of flags, further described below. A successful mmap () call shall return pa as its result. 

23139 The address range starting at pa and continuing for len bytes shall be legitimate for the possible 

23140 (not necessarily current) address space of the process. The range of bytes starting at off and 

23141 continuing for len bytes shall be legitimate for the possible (not necessarily current) offsets in the I 

23142 shm i tym file, shared memory object, or typed memory object represented by fildes . I 

23143 tym If fildes represents a typed memory object opened with either the I 

23144 POSIX_TYPED_MEM_ALLOCATE flag or the POSIX_TYPED_MEM_ALLOCATE_CONTIG I 

23145 flag, the memory object to be mapped shall be that portion of the typed memory object allocated I 

23146 by the implementation as specified below. In this case, if off is non-zero, the behavior of mmap () I 

23147 is undefined. If fildes refers to a valid typed memory object that is not accessible from the calling I 

23148 process, mmap () shall fail. I 

23149 The mapping established by mmap () replaces any previous mappings for those whole pages I 

23150 containing any part of the address space of the process starting at pa and continuing for len 

23151 bytes. 

23152 If the size of the mapped file changes after the call to mmap () as a result of some other operation 

23153 on the mapped file, the effect of references to portions of the mapped region that correspond to 

23154 added or removed portions of the file is unspecified. 

23155 shm The mmap () function is supported for regular files and shared memory objects. Support for any 

23156 other type of file is unspecified. 


23157 

23158 

23159 

23160 

23161 

23162 

23163 

23164 

23165 

23166 


The parameter prot determines whether read, write, execute, or some combination of accesses 
are permitted to the data being mapped. The prot should be either PROT_NONE or the bitwise- 
inclusive OR of one or more of the other flags in the following table, defined in the header 
<sys/mman.h>. 


Symbolic Constant 

Description 

PROT_READ 

PROT_WRITE 

PROT_EXEC 

PROT_NONE 

Data can be read. 

Data can be written. 

Data can be executed. 
Data cannot be accessed. 


23167 If an implementation cannot support the combination of access types specified by prot, the call 

23168 mpr to til inapt ) fails. An implementation may permit accesses other than those specified by prot; 

23169 however, if the _POSIX_MEMORY_PROTECTION option is supported, the implementation 
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23170 

23171 

23172 

23173 

23174 

23175 

23176 

23177 

23178 

23179 

23180 

23181 

23182 

23183 

23184 

23185 

23186 

23187 

23188 

23189 

23190 

23191 

23192 

23193 

23194 

23195 

23196 

23197 

23198 

23199 

23200 

23201 

23202 

23203 

23204 

23205 

23206 

23207 

23208 

23209 

23210 

23211 

23212 

23213 

23214 

23215 

23216 

23217 


shall not permit a write to succeed where PROT_WRITE has not been set or permit any access 
where PROT_NONE alone has been set. The implementation shall support at least the following 
values of prot: PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclusive OR of 
PROT_READ and PROT_WRITE. If the _POSIX_MEMORY_PROTECTION option is not 
supported, the result of any access that conflicts with the specified protection is undefined. The 
file descriptor fildes shall have been opened with read permission, regardless of the protection 
options specified. If PROT_WRITE is specified, the application shall ensure that it has opened I 
the file descriptor fildes with write permission unless MAP_PRIVATE is specified in the flags I 
parameter as described below. 

The parameter flags provides other information about the handling of the mapped data. The 
value of flags is the bitwise-inclusive OR of these options, defined in <sys/mman.h>: 


Symbolic Constant 

Description 

MAP_SHARED 

MAP_PRIVATE 

MAP_FIXED 

Changes are shared. 
Changes are private. 
Interpret addr exactly. 


Implementations that do not support the _POSIX_MAPPED_FILES option are not required to 
support MAP_PRIVATE. It is implementation-dependent whether MAP_FIXED shall be 
xsi supported. MAP_FIXED shall be supported on XSI-conformant systems. 

MAP_SHARED and MAP_PRIVATE describe the disposition of write references to the memory 
object. If MAP_SHARED is specified, write references change the underlying object. If 
MAP_PRIVATE is specified, modifications to the mapped data by the calling process shall be 
visible only to the calling process and shall not change the underlying object. It is unspecified 
whether modifications to the underlying object done after the MAP_PRIVATE mapping is 
established are visible through the MAP_PRIVATE mapping. Either MAP_SHARED or 
MAP_PRIVATE can be specified, but not both. The mapping type is retained across fork (). 

tym When fildes represents a typed memory object opened with either the 
POSIX_TYPED_MEM_ALLOCATE flag or the POSIX_TYPED_MEM_ALLOCATE_CONTIG 
flag, mmap() shall, if there are enough resources available, map len bytes allocated from the 
corresponding typed memory object which were not previously allocated to any process in any 
processor that may access that typed memory object. If there are not enough resources available, 
the function shall fail. If fildes represents a typed memory object opened with the 
POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, these allocated bytes shall be contiguous 
within the typed memory object, li fildes represents a typed memory object opened with the 
POSIX_TYPED_MEM_ ALLOC ATE flag, these allocated bytes may be composed of non¬ 
contiguous fragments within the typed memory object. If fildes represents a typed memory 
object opened with neither the POSIX_TYPED_MEM_ALLOCATE_CONTIG flag nor the 
POSIX_TYPED_MEM_ ALLOC ATE flag, len bytes starting at offset off within the typed memory 
object are mapped, exactly as when mapping a file or shared memory object. In this case, if two 
processes map an area of typed memory using the same off and len values and using file 
descriptors that refer to the same memory pool (either from the same port or from a different 
port), both processes shall map the same region of storage. 

When MAP_FIXED is set in th e flags argument, the implementation is informed that the value of 
man pa shall be addr, exactly. If MAP_FIXED is set, mmap () may return MAP_FAILED and set errno 
to [EINVAL]. If a MAP_FIXED request is successful, the mapping established by mmap() 
replaces any previous mappings for the process' pages in the range [pa,pa+len). 

When MAP_FIXED is not set, the implementation uses addr in an implementation-dependent 
manner to arrive at pa. The pa so chosen shall be an area of the address space that the 
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23254 
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23256 
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23258 

23259 
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implementation deems suitable for a mapping of ten bytes to the file. All implementations 
interpret an nddr value of 0 as granting the implementation complete freedom in selecting pa, 
subject to constraints described below. A non-zero value of addr is taken to be a suggestion of a 
process address near which the mapping should be placed. When the implementation selects a 
value for pa, it never places a mapping at address 0, nor does it replace any extant mapping. 

man The off argument is constrained to be aligned and sized according to the value returned by 

sysconf{ ) when passed _SC_PAGESIZE or _SC_PAGE_SIZE. When MAP_FIXED is specified, the I 
application shall ensure that the argument addr also meets these constraints. The I 
implementation performs mapping operations over whole pages. Thus, while the argument ten I 
need not meet a size or alignment constraint, the implementation shall include, in any mapping 
operation, any partial page specified by the range [pa,pa+len). 

The system always zero-fills any partial page at the end of an object. Further, the system never 
mpr writes out any modified portions of the last page of an object that are beyond its end. References 
within the address range starting at pa and continuing for ten bytes to whole pages following the 
end of an object result in delivery of a SIGBUS signal. 

man An implementation may generate SIGBUS signals when a reference would cause an error in the 
mapped object, such as out-of-space condition. 

man The mmapO function adds an extra reference to the file associated with the file descriptor fildes 
which is not removed by a subsequent close() on that file descriptor. This reference is removed 
when there are no more mappings to the file. 

The st_atime field of the mapped file may be marked for update at any time between the mmap () 
call and the corresponding munmap( ) call. The initial read or write reference to a mapped region 
shall cause the file's st_atime field to be marked for update if it has not already been marked for 
update. 

The st_ctime and stjntime fields of a file that is mapped with MAP_SHARED and PROT_WRITE 
shall be marked for update at some point in the interval between a write reference to the 
mapped region and the next call to msync( ) with MS_ASYNC or MS_SYNC for that portion of 
the file by any process. If there is no such call and if the underlying file is modified as a result of 
a write reference, then these fields shall be marked for update at some time after the write 
reference. 

man There may be implementation-dependent limits on the number of memory regions that can be 
mapped (per process or per system). 

xsi If such a limit is imposed, whether the number of memory regions that can be mapped by a 
process is decreased by the use of shmat( ) is implementation-dependent. 

If mmapO fails f° r reasons other than [EBADF], [EINVAL], or [ENOTSUP], some of the 
mappings in the address range starting at addr and continuing for ten bytes may have been 
unmapped. 

RETURN VALUE 

Upon successful completion, the mmap () function shall return the address at which the mapping 
was placed {pa); otherwise, it shall return a value of MAP_F AILED and set err no to indicate the 
error. The symbol MAP_FAILED is defined in the header <sys/mman.h>. No successful return 
from mmap () shall return the value MAP_FAILED. 

ERRORS 

The mmap () function shall fail if: 

[EACCES] Th e fildes argument is not open for read, regardless of the protection specified, I 

or fildes is not open for write and PROT_WRITE was specified for a 
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23264 


MAP_SHARED type mapping. 

23265 ML 

23266 

[EAGAIN] 

The mapping could not be locked in memory, if required by mlockall ( ), due to 
a lack of resources. 

23267 

[EBADF] 

Th efildes argument is not a valid open file descriptor. 

23268 MAN 

23269 

23270 

[EINVAL] 

The addr argument (if MAP_FIXED was specified) or off is not a multiple of 
the page size as returned by sysconff), or are considered invalid by the 
implementation. 

23271 

23272 

[EINVAL] 

The value of flags is invalid (neither MAP_PRIVATE nor MAP_SHARED is 
set). 

23273 MAN 

23274 

[EMFILE] 

The number of mapped regions would exceed an implementation-dependent 
limit (per process or per system). 

23275 

[ENODEV] 

Th efildes argument refers to a file whose type is not supported by mmap {). 

23276 

23277 

23278 

[ENOMEM] 

MAP_FIXED was specified, and the range [addr,addr+len) exceeds that allowed 
for the address space of a process; or, if MAP_FIXED was not specified and 
there is insufficient room in the address space to effect the mapping. 

23279 ML 

23280 

[ENOMEM] 

The mapping could not be locked in memory, if required by mlockall (), 
because it would require more space than the system is able to supply. 

23281 

23282 


MAP_FIXED or MAP_PRIVATE was specified in the flags argument and the 
implementation does not support this functionality. 

23283 TYM 

23284 

[ENOMEM] 

Not enough unallocated memory resources remain in the typed memory 
object designated by fildes to allocate len bytes. 

23285 

23286 

[ENOTSUP] 

The implementation does not support the combination of accesses requested 
in the prot argument. 

23287 

[ENXIO] 

Addresses in the range [off,off+len) are invalid for the object specified by fildes. 

23288 

23289 

[ENXIO] 

MAP_FIXED was specified in flags and the combination of addr, len, and off is 
invalid for the object specified by fildes. 

23290 TYM 

23291 

[ENXIO] 

Th efildes argument refers to a typed memory object that is not accessible from 
the calling process. 

23292 MAN 

23293 

[EOVERFLOW] 

The file is a regular file and the value of off plus len exceeds the offset 
maximum established in the open file description associated with fildes. 

23294 EXAMPLES 

23295 None. 


23296 APPLICATION USAGE 

23297 Use of mmap() may reduce the amount of memory available to other memory allocation 

23298 functions. 

23299 

23300 

23301 

Use of MAP_FIXED may result in unspecified behavior in further use of malloc() and shmat(). 
The use of MAP_FIXED is discouraged, as it may prevent an implementation from making the 
most effective use of resources. 

23302 

23303 

The application must ensure correct synchronization when using nimap ( ) in conjunction with 
any other file access method, such as read( ) and write ( ), standard input/output, and shmat {). 

23304 

23305 

The nimap () function allows access to resources via address space manipulations, instead of 
read()/write(). Once a file is mapped, all a process has to do to access it is use the data at the 


740 


Technical Standard (2000) (Draft February 29, 2000) 




System Interfaces 


mmapO 


23306 

23307 

23308 

23309 

23310 

23311 
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23348 
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address to which the file was mapped. So, using pseudo-code to illustrate the way in which an 
existing program might be changed to use mmap (), the following: 

fildes = open (...) 

lseek(fildes, some_offset) 

read(fildes, buf, len) 

/* Use data in buf. */ 

becomes: 

fildes = open (...) 

address = mmap(0, len, PROT_READ, MAP_PRIVATE, fildes, some_offset) 

/* Use data at address. */ 

The [EINVAL] error above is marked EX because it is defined as an optional error in the POSIX 
Realtime Extension. 

RATIONALE 

After considering several other alternatives, it was decided to adopt the mmap () definition found 
in SVR4 for mapping memory objects into process address spaces. The SVR4 definition is 
minimal, in that it describes only what has been built, and what appears to be necessary for a 
general and portable mapping facility. 

Note that while mmap () was first designed for mapping files, it is actually a general-purpose 
mapping facility. It can be used to map any appropriate object, such as memory, files, devices, 
and so on, into the address space of a process. 

When a mapping is established, it is possible that the implementation may need to map more 
than is requested into the address space of the process because of hardware requirements. An 
application, however, cannot count on this behavior. Implementations that do not use a paged 
architecture may simply allocate a common memory region and return the address of it; such 
implementations probably do not allocate any more than is necessary. References past the end of 
the requested area are unspecified. 

If an application requests a mapping that would overlay existing mappings in the process, it 
might be desirable that an implementation detect this and inform the application. However, the 
default, portable (not MAP_FIXED) operation does not overlay existing mappings. On the other 
hand, if the program specifies a fixed address mapping (which requires some implementation 
knowledge to determine a suitable address, if the function is supported at all), then the program 
is presumed to be successfully managing its own address space and should be trusted when it 
asks to map over existing data structures. Furthermore, it is also desirable to make as few system 
calls as possible, and it might be considered onerous to require an munmap( ) before an mmap() 
to the same address range. This volume of IEEE Std. 1003.1-200x specifies that the new 
mappings replace any existing mappings, following existing practice in this regard. 

It is not expected, when the Memory Protection option is supported, that all hardware 
implementations are able to support all combinations of permissions at all addresses. When this 
option is supported, implementations are required to disallow write access to mappings without 
write permission and to disallow access to mappings without any access permission. Other than 
these restrictions, implementations may allow access types other than those requested by the 
application. For example, if the application requests only PROT_WRITE, the implementation 
may also allow read access. A call to mmap () fails if the implementation cannot support allowing 
all the access requested by the application. For example, some implementations cannot support 
a request for both write access and execute access simultaneously. All implementations 
supporting the Memory Protection option must support requests for no access, read access, 
write access, and both read and write access. Strictly conforming code must only rely on the 
required checks. These restrictions allow for portability across a wide range of hardware. 
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23354 The MAP_FIXED address treatment is likely to fail for non-page-aligned values and for certain 

23355 architecture-dependent address ranges. Conforming implementations cannot count on being 

23356 able to choose address values for MAP_FIXED without utilizing non-portable, implementation- 

23357 dependent knowledge. Nonetheless, MAP_FIXED is provided as a standard interface 

23358 conforming to existing practice for utilizing such knowledge when it is available. 

23359 Similarly, in order to allow implementations that do not support virtual addresses, support for 

23360 directly specifying any mapping addresses via MAP_FIXED is not required and thus a 

23361 conforming application may not count on it. 

23362 The MAP_PRIVATE function can be implemented efficiently when memory protection hardware 

23363 is available. When such hardware is not available, implementations can implement such 

23364 "mappings" by simply making a real copy of the relevant data into process private memory, 

23365 though this tends to behave similarly to read( ). 

23366 The function has been defined to allow for many different models of using shared memory. 

23367 However, all uses are not equally portable across all machine architectures. In particular, the 

23368 mmap () function allows the system as well as the application to specify the address at which to 

23369 map a specific region of a memory object. The most portable way to use the function is always to 

23370 let the system choose the address, specifying NUEL as the value for the argument nddr and not 

23371 to specify MAP_FIXED. 

23372 If it is intended that a particular region of a memory object be mapped at the same address in a 

23373 group of processes (on machines where this is even possible), then MAP_FIXED can be used to 

23374 pass in the desired mapping address. The system can still be used to choose the desired address 

23375 if the first such mapping is made without specifying MAP_FIXED, and then the resulting 

23376 mapping address can be passed to subsequent processes for them to pass in via MAP_FIXED. 

23377 The availability of a specific address range cannot be guaranteed, in general. 

23378 The mmap () function can be used to map a region of memory that is larger than the current size 

23379 of the object. Memory access within the mapping but beyond the current end of the underlying 

23380 objects may result in SIGBUS signals being sent to the process. The reason for this is that the size 

23381 of the object can be manipulated by other processes and can change at any moment. The 

23382 implementation should tell the application that a memory reference is outside the object where 

23383 this can be detected; otherwise, written data may be lost and read data may not reflect actual 

23384 data in the object. 

23385 Note that references beyond the end of the object do not extend the object as the new end cannot 

23386 be determined precisely by most virtual memory hardware. Instead, the size can be directly 

23387 manipulated by/truncate (). 

23388 Process memory locking does apply to shared memory regions, and the MEMEOCK_FUTURE 

23389 argument to memlockall () can be relied upon to cause new shared memory regions to be 

23390 automatically locked. 

23391 Existing implementations of mmap () return the value -1 when unsuccessful. Since the casting of 

23392 this value to type void 51 ' cannot be guaranteed by the ISO C standard to be distinct from a 

23393 successful value, this volume of IEEE Std. 1003.1-200x defines the symbol MAP_FAILED, which 

23394 a conforming implementation does not return as the result of a successful call. 

23395 FUTURE DIRECTIONS 

23396 None. 

23397 SEE ALSO 

23398 exec, fcntl(), fork (), lockf(), msync(), munmap(), mprotect(), posix_typed_memjopen (), slimat(), 

23399 sysconf( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <sys/mman.h> 
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CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 

Aligned with mmap () in the POSIX Realtime Extension as follows: 

• The DESCRIPTION is extensively reworded. 

• The [EAGAIN] and [ENOTSUP] mandatory error conditions are added. 

• New cases of [ENOMEM] and [ENXIO] are added as mandatory error conditions. 

• The value returned on failure is the value of the constant MAP_FAILED; this was previously 
defined as -1. 

Large File Summit extensions are added. 

Issue 6 

The mmap( ) function is marked as part of the _POSIX_MAPPED_FILES option. 

The Open Group corrigenda item U028/6 has been applied, changing (void *)-l to 
MAP_FAILED. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The DESCRIPTION is updated to described the use of MAP_FIXED. 

• The DESCRIPTION is updated to describe the addition of an extra reference to the file 
associated with the file descriptor passed to mmap( ). 

• The DESCRIPTION is updated to state that there may be implementation-dependent limits 
on the number of memory regions that can be mapped. 

• The DESCRIPTION is updated to describe constraints on the alignment and size of the off 
argument. 

• The [EINVAL] and [EMFILE] error conditions are added. 

• The [EOVERFLOW] error condition is added. This change is to support large files. 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The DESCRIPTION is updated to describe the cases when MAP_PRIVATE and MAP_FIXED 
need not be supported. 

The following changes are made for alignment with IEEE Std. 1003.1j-2000: 

• Semantics for typed memory objects are added to the DESCRIPTION. 

• New [ENOMEM] and [ENXIO] errors are added to the ERRORS section. 

• The posix_typed_mem_open () function is added to the SEE ALSO section. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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23434 NAME 

23435 modf — decompose a floating-point number 

23436 SYNOPSIS 

23437 #include <math.h> 

23438 double modf (double x, double * iptr) ; 

23439 DESCRIPTION 

23440 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

23441 conflict between the requirements described here and the ISO C standard is unintentional. This I 

23442 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

23443 The modf( ) function shall break the argument x into integral and fractional parts, each of which 

23444 has the same sign as the argument. It stores the integral part as a double in the object pointed to 

23445 by iptr. 

23446 An application wishing to check for error situations should set errno to 0 before calling modf( ). If 

23447 errno is non-zero on return, or the return value is NaN, an error has occurred. 

23448 RETURN VALUE 

23449 Upon successful completion, modf( ) shall return the signed fractional part of x. 

23450 xsi If x is NaN, NaN shall be returned, errno may be set to [EDOM], and *iptr shall be set to NaN. 

23451 If the correct value would cause underflow, 0 shall be returned and errno may be set to 

23452 [ERANGE]. 

23453 ERRORS 

23454 The rnodfi ) function may fail if: 

23455 xsi [EDOM] The value of x is NaN. 

23456 [ERANGE] The result underflows. 

23457 xsi No other errors shall occur. 

23458 EXAMPLES 

23459 None. 

23460 APPLICATION USAGE 

23461 The modf( ) function computes the function result and *iptr such that: 

23462 a = modf (x, Siptr) 

23463 x == a+iptr 

23464 allowing for the usual floating point inaccuracies. 

23465 RATIONALE 

23466 None. 

23467 FUTURE DIRECTIONS 

23468 None. 

23469 SEE ALSO 

23470 frexp (), isnan (), ldexp(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

23471 <math.h> 

23472 CHANGE HISTORY 

23473 First released in Issue 1. 

23474 Derived from Issue 1 of the SVID. 
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23475 Issue 4 

23476 References to matherr {) are removed. 

23477 The name of the first argument is changed from value to x. 

23478 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

23479 ISO C standard and to rationalize error handling in the mathematics functions. 

23480 The return value specified for [EDOM] is marked as an extension. 


23481 Issue 5 

23482 The DESCRIPTION is updated to indicate how an application should check for an error. This 

23483 text was previously published in the APPLICATION USAGE section. 
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23484 NAME 

23485 mprotect — set protection of memory mapping 

23486 SYNOPSIS 

23487 mpr #include <sys/mman.h> 

23488 int mprotect (void *addr, size_t len, int prot) ; 

23489 

23490 DESCRIPTION 

23491 The mprotect () function shall change the access protections to be that specified by prot for those 

23492 whole pages containing any part of the address space of the process starting at address addr and 

23493 continuing for len bytes. The parameter prot determines whether read, write, execute, or some 

23494 combination of accesses are permitted to the data being mapped. The prot argument should be 

23495 either PROT_NONE or the bitwise-inclusive OR of one or more of PROT_READ, PROT_WRITE, 

23496 and PROT_EXEC. 

23497 If an implementation cannot support the combination of access types specified by prot, the call 

23498 to mprotect () shall fail. 

23499 An implementation may permit accesses other than those specified by prot; however, no 

23500 implementation permits a write to succeed where PROT_WRITE has not been set or permits any 

23501 access where PROT_NONE alone has been set. Implementations shall support at least the 

23502 following values of prot: PROT_NONE, PROT_READ, PROT_WRITE, and the bitwise-inclusive 

23503 OR of PROT_READ and PROT_WRITE. If PROT_WRITE is specified, the application shall I 

23504 ensure that it has opened the mapped objects in the specified address range with write I 

23505 permission, unless MAP_PRIVATE was specified in the original mapping, regardless of whether I 

23506 the file descriptors used to map the objects have since been closed. 

23507 man The implementation shall require that addr be a multiple of the page size as returned by 

23508 sysconf(). 

23509 The behavior of this function is unspecified if the mapping was not established by a call to 

23510 mmapi ). 

23511 When mprotect () fails for reasons other than [EINVAL], the protections on some of the pages in 

23512 the range [addr , addr+len) may have been changed. 

23513 RETURN VALUE 

23514 Upon successful completion, mprotect () shall return 0; otherwise, it shall return -1 and set errno 

23515 to indicate the error. 

23516 ERRORS 

23517 The mprotect () function shall fail if: 

23518 [EACCES] The prot argument specifies a protection that violates the access permission 

23519 the process has to the underlying memory object. 

23520 [EAGAIN] The prot argument specifies PROT_WRITE over a MAP_PRIVATE mapping 

23521 and there are insufficient memory resources to reserve for locking the private 

23522 page. 

23523 man [EINVAL] The addr argument is not a multiple of the page size as returned by sysconf( ). 

23524 [ENOMEM] Addresses in the range [addr , addr+len) are invalid for the address space of a 

23525 process, or specify one or more pages which are not mapped. 

23526 [ENOMEM] The prot argument specifies PROT_WRITE on a MAP_PRIVATE mapping, and 

23527 it would require more space than the system is able to supply for locking the 

23528 private pages, if required. 
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23529 

23530 

23531 

23532 

23533 

23534 

23535 

23536 

23537 

23538 

23539 

23540 

23541 

23542 

23543 

23544 

23545 

23546 

23547 

23548 

23549 

23550 

23551 

23552 

23553 

23554 

23555 

23556 

23557 

23558 


[ENOTSUP] The implementation does not support the combination of accesses requested 
in the prot argument. 

EXAMPLES 

None. 

APPLICATION USAGE 

The [EINVAL] error above is marked EX because it is defined as an optional error in the POSIX 
Realtime Extension. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

mmap(), sysconf(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

<sys/mman.h> 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 

Aligned with mprotect () in the POSIX Realtime Extension as follows: 

• The DESCRIPTION is largely reworded. 

• [ENOTSUP] and a second form of [ENOMEM] are added as mandatory error conditions. 

• [E AG AIN] is moved from the optional to the mandatory error conditions. 

Issue 6 

The mprotect () function is marked as part of the _POSIX_MEMORY_PROTECTION option. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The DESCRIPTION is updated to state that implementations require addr to be a multiple of 
the page size as returned by sysconf (). 

• The [EINVAL] error condition is added. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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23559 NAME 

23560 mq_close — close a message queue (REALTIME) 

23561 SYNOPSIS 

23562 MSG tinclude <mqueue.h> 

23563 int mq_close (mqd_t mqdes) ; 

23564 

23565 DESCRIPTION 

23566 The mq_close() function shall remove the association between the message queue descriptor, 

23567 mqdes, and its message queue. The results of using this message queue descriptor after 

23568 successful return from this mq_close( ), and until the return of this message queue descriptor 

23569 from a subsequent mq_open (), are undefined. 

23570 If the process has successfully attached a notification request to the message queue via this 

23571 mqdes, this attachment shall be removed, and the message queue is available for another process 

23572 to attach for notification. 

23573 RETURN VALUE 

23574 Upon successful completion, the mq_close( ) function shall return a value of zero; otherwise, the 

23575 function shall return a value of -1 and set errno to indicate the error. 

23576 ERRORS 

23577 The mq_close( ) function shall fail if: 

23578 [EBADF] The mqdes argument is not a valid message queue descriptor. 

23579 EXAMPLES 

23580 None. 

23581 APPLICATION USAGE 

23582 None. 

23583 RATIONALE 

23584 None. 

23585 FUTURE DIRECTIONS 

23586 None. 

23587 SEE ALSO 

23588 mqjopen (), mq_unlink (), msgctl(), msgget (), msgrcv (), msgsnd (), the System Interface Definitions 

23589 volume of IEEE Std. 1003.1-200x, <mqueue.h> 

23590 CHANGE HISTORY 

23591 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

23592 Issue 6 

23593 The mq_close{ ) function is marked as part of the _POSIX_MESSAGE_PASSING option. 

23594 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

23595 implementation does not support the _POSIX_MESSAGE_PASSING option. 
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23596 NAME 

23597 mq_getattr — get message queue attributes (REALTIME) 

23598 SYNOPSIS 

23599 MSG tinclude <mqueue.h> 

23600 int mq_getattr (mqd_t mqdes, struct mq_attr *mqstat) ; 

23601 

23602 DESCRIPTION 

23603 The mqdes argument specifies a message queue descriptor. 

23604 The mq_getattr( ) function is used to get status information and attributes of the message queue 

23605 and the open message queue description associated with the message queue descriptor. 

23606 The results are returned in the mq_attr structure referenced by the mqstat argument. 

23607 Upon return, the following members have the values associated with the open message queue 

23608 description as set when the message queue was opened and as modified by subsequent 

23609 mq_setattr( ) calls: mq_flags. 

23610 The following attributes of the message queue shall be returned as set at message queue 

23611 creation: mq_maxmsg, mqjnsgsize. 

23612 Upon return, the following members within the mq_attr structure referenced by the mqstat 

23613 argument are set to the current state of the message queue: 

23614 mq_curmsgs The number of messages currently on the queue. 

23615 RETURN VALUE 

23616 Upon successful completion, the mq_getattr( ) function shall return zero. Otherwise, the function 

23617 shall return -1 and set errno to indicate the error. 

23618 ERRORS 

23619 The mq_getattr( ) function shall fail if: 

23620 [EBADF] The mqdes argument is not a valid message queue descriptor. 

23621 EXAMPLES 

23622 None. 

23623 APPLICATION USAGE 

23624 None. 

23625 RATIONALE 

23626 None. 

23627 FUTURE DIRECTIONS 

23628 None. 

23629 SEE ALSO 

23630 mqjopen (), mq_send(), mq_setattr {), mq_timedsend(), msgctl(), msgget(), msgrcv(), msgsnd(), the I 

23631 System Interface Definitions volume of IEEE Std. 1003.1-200x, <mqueue.h> 

23632 CHANGE HISTORY 

23633 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 

23634 Issue 6 

23635 The mq_getattr( ) function is marked as part of the _POSIX_MESSAGE_PASSING option. 

23636 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

23637 implementation does not support the _POSIX_MESSAGE_PASSING option. I 
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23638 

23639 


The mq_timedsend() function is added to the SEE ALSO section for alignment with I 
IEEE Std. 1003.1d-1999. I 
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23640 NAME 

23641 mq_notify — notify process that a message is available (REALTIME) 

23642 SYNOPSIS 

23643 MSG tinclude <mqueue.h> 

23644 int mq_notify (mqd_t mqdes, const struct sigevent * notification) ; 

23645 

23646 DESCRIPTION 

23647 If the argument notification is not NULL, this function registers the calling process to be notified 

23648 of message arrival at an empty message queue associated with the specified message queue 

23649 descriptor, mqdes. The notification specified by the notification argument shall be sent to the 

23650 process when the message queue transitions from empty to non-empty. At any time, only one 

23651 process may be registered for notification by a message queue. If the calling process or any other 

23652 process has already registered for notification of message arrival at the specified message queue, 

23653 subsequent attempts to register for that message queue fail. 

23654 If notification is NULL and the process is currently registered for notification by the specified 

23655 message queue, the existing registration is removed. 

23656 When the notification is sent to the registered process, its registration shall be removed. The 

23657 message queue shall then be available for registration. 

23658 If a process has registered for notification of message arrival at a message queue and some 

23659 thread is blocked in mq_receive() waiting to receive a message when a message arrives at the 

23660 queue, the arriving message satisfies the appropriate mq_receive( ). The resulting behavior is as if 

23661 the message queue remains empty, and no notification is sent. 

23662 RETURN VALUE 

23663 Upon successful completion, the mq_notify( ) function shall return a value of zero; otherwise, the 

23664 function shall return a value of -1 and set errno to indicate the error. 

23665 ERRORS 

23666 The mq_notify{ ) function shall fail if: 

23667 [EBADF] The mqdes argument is not a valid message queue descriptor. 

23668 [EBUSY] A process is already registered for notification by the message queue. 

23669 EXAMPLES 

23670 None. 

23671 APPLICATION USAGE 

23672 None. 

23673 RATIONALE 

23674 None. 

23675 FUTURE DIRECTIONS 

23676 None. 

23677 SEE ALSO 

23678 mq_open (), mq_send(), mq_timedsend{ ), msgctl(), msgget(), msgrcv{), msgsnd (), the System I 

23679 Interface Definitions volume of IEEE Std. 1003.1-200x, <mqueue.h> 

23680 CHANGE HISTORY 

23681 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 
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23682 

23683 

23684 

23685 

23686 

23687 


Issue 6 

The mq_notify () function is marked as part of the _POSIX_MESSAGE_PASSING option. 

The [ENOSYS] error condition has been removed as stubs need not be provided if an 
implementation does not support the _POSIX_MESSAGE_PASSING option. I 

The mq_timedsend () function is added to the SEE ALSO section for alignment with I 
IEEE Std. 1003.1d-1999. I 
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23688 NAME 

23689 mq_open — open a message queue (REALTIME) 

23690 SYNOPSIS 

23691 MSG #include <mqueue.h> 

23692 mqd_t mq_open (const char *name, int of lag, ...); 

23693 


23694 DESCRIPTION 

23695 The mq_open () function shall establish the connection between a process and a message queue 

23696 with a message queue descriptor. It creates an open message queue description that refers to the 

23697 message queue, and a message queue descriptor that refers to that open message queue 

23698 description. The message queue descriptor is used by other functions to refer to that message 

23699 queue. The name argument points to a string naming a message queue. It is unspecified whether 

23700 the name appears in the file system and is visible to other functions that take path names as 

23701 arguments. The name argument conforms to the construction rules for a path name. If name 

23702 begins with the slash character, then processes calling mqjjpen () with the same value of name 

23703 refer to the same message queue object, as long as that name has not been removed. If name does 

23704 not begin with the slash character, the effect is implementation-dependent. The interpretation of 

23705 slash characters other than the leading slash character in name is implementation-dependent. If 

23706 the name argument is not the name of an existing message queue and creation is not requested, 

23707 mqjopen () shall fail and return an error. 

23708 The oflag argument requests the desired receive and/or send access to the message queue. The 

23709 requested access permission to receive messages or send messages is granted if the calling 

23710 process would be granted read or write access, respectively, to an equivalently protected file. 

23711 The value of oflag is the bitwise-inclusive OR of values from the following list. Applications 

23712 specify exactly one of the first three values (access modes) below in the value of oflag: 


23713 

23714 

23715 

23716 


0_RDONLY Open the message queue for receiving messages. The process can use the 
returned message queue descriptor with mq_receive(), but not mq_send(). A 
message queue may be open multiple times in the same or different processes 
for receiving messages. 


23717 

23718 

23719 

23720 


0_WRONLY Open the queue for sending messages. The process can use the returned 
message queue descriptor with mq_send() but not mq_receive(). A message 
queue may be open multiple times in the same or different processes for 
sending messages. 


23721 

23722 

23723 

23724 


0_RDWR Open the queue for both receiving and sending messages. The process can use 

any of the functions allowed for 0_RDONLY and 0_WRONLY. A message 
queue may be open multiple times in the same or different processes for 
sending messages. 


23725 Any combination of the remaining flags may be specified in the value of oflag: 


23726 

23727 

23728 

23729 

23730 

23731 

23732 

23733 

23734 


0_CREAT This option is used to create a message queue, and it requires two additional 

arguments: mode, which is of type mode_t, and attr, which is a pointer to a 
mq_attr structure. If the path name name has already been used to create a 
message queue that still exists, then this flag has no effect, except as noted 
under 0_EXCL. Otherwise, a message queue is created without any messages 
in it. The user ID of the message queue is set to the effective user ID of the 
process, and the group ID of the message queue is set to the effective group ID 
of the process. The file permission bits are set to the value of mode. When bits 
in mode other than file permission bits are set, the effect is implementation- 
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23735 dependent. If attr is NULL, the message queue is created with 

23736 implementation-dependent default message queue attributes. If attr is non- 

23737 NULL and the calling process has the appropriate privilege on name, the 

23738 message queue mqjnaxmsg and mqjnsgsize attributes are set to the values of 

23739 the corresponding members in the mq_attr structure referred to by attr. If attr 

23740 is non-NULL, but the calling process does not have the appropriate privilege 

23741 on name, the mqjopen () function shall fail and return an error without creating 

23742 the message queue. 

23743 0_EXCL If 0_EXCL and 0_CREAT are set, mqjopen () fails if the message queue name 

23744 exists. The check for the existence of the message queue and the creation of 

23745 the message queue if it does not exist are atomic with respect to other 

23746 processes executing mqjopen () naming the same name with 0_EXCL and 

23747 CLCREAT set. If 0_EXCL is set and CLCREAT is not set, the result is 

23748 undefined. 

23749 0_N0NBL0CK The setting of this flag is associated with the open message queue description 

23750 and determines whether a mq_send() or mqjeceive() waits for resources or 

23751 messages that are not currently available, or fails with errno set to [EAGAIN]; 

23752 see mqjsend () and mq_receive( ) for details. 

23753 The mqjopen () function does not add or remove messages from the queue. 

23754 RETURN VALUE 

23755 Upon successful completion, the function shall return a message queue descriptor; otherwise, 

23756 the function shall return (mqd_t)-l and set errno to indicate the error. 


23757 ERRORS 


The mqjopen () function shall fail if: 

[EACCES] The message queue exists and the permissions specified by oflag are denied, or 

the message queue does not exist and permission to create the message queue 
is denied. 

[EEXIST] 0_CREAT and 0_EXCL are set and the named message queue already exists. 

[EINTR] The mqjopen () function was interrupted by a signal. 

[EINVAL] The mqjopen () function is not supported for the given name. 

[EINVAL] 0_CREAT was specified in oflag, the value of attr is not NULL, and either 

mqjnaxmsg or mqjnsgsize was less than or equal to zero. 

[EMFILE] Too many message queue descriptors or file descriptors are currently in use by 

this process. 

[ENAMETOOLONG] 

The length of the name string exceeds {PATH_MAX}, or a path name 
component is longer than |NAME_MAX} while _POSIX_NO_TRUNC is in 
effect. 

[ENFILE] Too many message queues are currently open in the system. 

[ENOENT] CLCREAT is not set and the named message queue does not exist. 

[ENOSPC] There is insufficient space for the creation of the new message queue. 
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23776 EXAMPLES 

23777 None. 

23778 APPLICATION USAGE 

23779 None. 

23780 RATIONALE 

23781 None. 

23782 FUTURE DIRECTIONS 

23783 None. 


23784 SEE ALSO 

23785 mq_close(), mq_getattr( ), mq_receive( ), mq_send(), mq_setattr( ), mq_timedreceive {), mqjtimedsend (), I 

23786 mq_nnlink(), msgctl(), msgget() r msgrcv (), msgsnd(), the System Interface Definitions volume of 

23787 IEEE Std. 1003.1-200x, <mqueue.h> 

23788 CHANGE HISTORY 

23789 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 


23790 Issue 6 

23791 The mq_open () function is marked as part of the _POSIX_MESSAGE_PASSING option. 


23792 

23793 

23794 

23795 


The [ENOSYS] error condition has been removed as stubs need not be provided if an 
implementation does not support the _POSIX_MESSAGE_PASSING option. I 

The mq_timedreceive{) and mqjtimedsend () functions are added to the SEE ALSO section for I 
alignment with IEEE Std. 1003.1d-1999. I 


System Interfaces, Issue 6 


755 



mq_receive() 


System Interfaces 


23796 NAME 

23797 mq_receive, mq_timedreceive — receive a message from a message queue (REALTIME) 

23798 SYNOPSIS 

23799 MSG #include <mqueue.h> 

23800 

23801 

23802 

23803 MSG TMO #include <mqueue.h> 

23804 #include <time.h> 

23805 int mq_timedreceive (mqd_t mqdes, char *msg_ptr, size_t msg_len, 

23806 unsigned int *msg_prio, const struct timespec * abs_timeout) ; 

23807 

23808 Notes to Reviewers 

23809 This section zvith side shading will not appear in the final copy. - Ed. 

23810 mq_receive( ) returns ssize_t, and mq_timedreceive( ) returns int. I believe they were both meant to 

23811 return the same type, probably ssize_t. 

23812 DESCRIPTION 

23813 The mq_receive( ) function is used to receive the oldest of the highest priority message(s) from the 

23814 message queue specified by mqdes. If the size of the buffer in bytes, specified by the msg_len 

23815 argument, is less than the mq_msgsize attribute of the message queue, the function shall fail and 

23816 return an error. Otherwise, the selected message is removed from the queue and copied to the 

23817 buffer pointed to by the msg_ptr argument. 

23818 man If the value of msg_len is greater than {SSIZE_MAX}, the result is implementation-dependent. 

23819 If the argument msgjprio is not NULL, the priority of the selected message is stored in the 

23820 location referenced by msg_prio. 

23821 If the specified message queue is empty and 0_NONBLOCK is not set in the message queue 

23822 description associated with mqdes, mq_receive() blocks until a message is enqueued on the 

23823 message queue or until mq_receive( ) is interrupted by a signal. If more than one thread is waiting 

23824 to receive a message when a message arrives at an empty queue and the Priority Scheduling 

23825 option is supported, then the thread of highest priority that has been waiting the longest shall be 

23826 selected to receive the message. Otherwise, it is unspecified which waiting thread receives the 

23827 message. If the specified message queue is empty and 0_NONBLOCK is set in the message 

23828 queue description associated with mqdes, no message is removed from the queue, and 

23829 mq_receive( ) shall return an error. 

23830 tmo The mq_timedreceive( ) function is used to receive the oldest of the highest priority messages from 

23831 the message queue specified by mqdes as in the mq_receive( ) function. However, if 

23832 0_NONBLOCK was not specified when the message queue was opened via the mq_open() 

23833 function, and no message exists on the queue to satisfy the receive, the wait for such a message 

23834 will be terminated when the specified timeout expires. If 0_NONBLOCK is set, this function 

23835 shall behave identically to mq_receive( ). 

23836 The timeout expires when the absolute time specified by abs_timeout passes, as measured by the 

23837 clock on which timeouts are based (that is, when the value of that clock equals or exceeds 

23838 abs_timeont), or if the absolute time specified by abs_timeout has already been passed at the time 

23839 of the call. If the Timers option is supported, the timeout is based on the CLOCK_REALTIME 

23840 clock; if the Timers option is not supported, the timeout is based on the system clock as returned 


ssize_t mq_receive(mqd_t mqdes, char *msg_ptr, size_t msg_len , 
unsigned int *msg_prio) ; 
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23841 by the time() function. The resolution of the timeout is the resolution of the clock on which it is I 

23842 based. The timespec argument is defined as a structure in the <time.h> header. I 

23843 Under no circumstance shall the operation fail with a timeout if a message can be removed from I 

23844 the message queue immediately. The validity of the abs_timeout parameter need not be checked I 

23845 if a message can be removed from the message queue immediately. I 

23846 RETURN VALUE 

23847 tmo Upon successful completion, the mq_receive() and mq_timedreceive () functions shall return the I 

23848 length of the selected message in bytes and the message shall be removed from the queue. I 

23849 Otherwise, no message shall be removed from the queue, the functions shall return a value of -1, I 

23850 and set errno to indicate the error. I 

23851 ERRORS 

23852 tmo The mq_receive( ) and mq_timedreceive( ) functions shall fail if: I 

23853 [E AG AIN] 0_N0NBL0CK was set in the message description associated with mqdes, 

23854 and the specified message queue is empty. 

23855 [EBADF] The mqdes argument is not a valid message queue descriptor open for reading. 

23856 [EMSGSIZE] The specified message buffer size, msg_len, is less than the message size 

23857 attribute of the message queue. 

23858 tmo [EINTR] The mq_receive( ) or mq_timedreceive( ) operation was interrupted by a signal. I 

23859 tmo [EINVAL] The thread would have blocked, and the abs_timeont parameter specified a I 

23860 nanoseconds field value less than zero or greater than or equal to 1000 I 

23861 million. I 

23862 tmo [ETIMEDOUT] The 0_NONBLOCK flag was not set when the message queue was opened, I 

23863 but no message arrived on the queue before the specified timeout expired. I 

23864 tmo The mq_receive( ) and mq_timedreceive( ) functions may fail if: I 

23865 [EBADMSG] The implementation has detected a data corruption problem with the 

23866 message. 

23867 EXAMPLES 

23868 None. 

23869 APPLICATION USAGE 

23870 None. 

23871 RATIONALE 

23872 None. 

23873 FUTURE DIRECTIONS 

23874 None. 

23875 SEE ALSO 

23876 mq_open (), mq_send (), mqjtimedsend (), msgctl (), msgget (), msgrcv( ), msgsnd (), time( ), the System I 

23877 Interface Definitions volume of IEEE Std. 1003.1-200x, <mqueue.h>, <time.h> I 

23878 CHANGE HISTORY 

23879 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 

23880 Issue 6 

23881 The mq_receive() function is marked as part of the _POSIX_MESSAGE_PASSING option. 

23882 The Open Group corrigenda item U021/4 has been applied. The DESCRIPTION is changed to 

23883 refer to msg_len rather than maxsize. 
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23884 

23885 

23886 

23887 

23888 

23889 

23890 

23891 


The [ENOSYS] error condition has been removed as stubs need not be provided if an 
implementation does not support the _POSIX_MESSAGE_PASSING option. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In this function it is possible for the return value to exceed the range of the type ssize_t (since 
size_t has a larger range of positive values than ssize_t). A sentence restricting the size of 
the size_t object is added to the description to resolve this conflict. 

The mq_timedreceive () function is added for alignment with IEEE Std. 1003.1d-1999. 
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23892 NAME 

23893 mq_send, mq_timedsend — send a message to a message queue (REALTIME) 

23894 SYNOPSIS 

23895 MSG tinclude <mqueue.h> 

23896 

23897 

23898 

23899 MSG TMO 

23900 

23901 

23902 

23903 

23904 DESCRIPTION 

23905 The viq_send() function shall add the message pointed to by the argument msg_ptr to the 

23906 message queue specified by mqdes. The visgjen argument specifies the length of the message in 

23907 bytes pointed to by msgjptr. The value of msg_len is less than or equal to the mqjnsgsize 

23908 attribute of the message queue, or mq_send( ) shall fail. 

23909 If the specified message queue is not full, mq_send( ) behaves as if the message shall be inserted 

23910 into the message queue at the position indicated by the msg_prio argument. A message with a 

23911 larger numeric value of msgjprio shall be inserted before messages with lower values of 

23912 visgjprio. A message shall be inserted after other messages in the queue, if any, with equal 

23913 visgjprio. The value of visgjprio shall be less than {MQ_PRIO_MAX}. 

23914 If the specified message queue is full and 0_NONBLOCK is not set in the message queue 

23915 description associated with mqdes, mq_send() shall block until space becomes available to 

23916 enqueue the message, or until mqjsend () is interrupted by a signal. If more than one thread is 

23917 waiting to send when space becomes available in the message queue and the Priority Scheduling 

23918 option is supported, then the thread of the highest priority that has been waiting the longest 

23919 shall be unblocked to send its message. Otherwise, it is unspecified which waiting thread is 

23920 unblocked. If the specified message queue is full and 0_NONBLOCK is set in the message 

23921 queue description associated with mqdes, the message shall not be queued and mq_send () shall 

23922 return an error. 

23923 tmo The mq_timedsend() function adds a message to the message queue specified by mqdes in the 

23924 manner defined for the mq_send () function. However, if the specified message queue is full and 

23925 0_NONBLOCK is not set in the message queue description associated with mqdes, the wait for 

23926 sufficient room in the queue shall be terminated when the specified timeout expires. If 

23927 0_NONBLOCK is set in the message queue description, this function shall behave identically to 

23928 mq_send(). 

23929 The timeout expires when the absolute time specified by abs_tivieont passes, as measured by the 

23930 clock on which timeouts are based (that is, when the value of that clock equals or exceeds 

23931 abs_timeout), or if the absolute time specified by abs_tivieont has already been passed at the time 

23932 of the call. If the Timers option is supported, the timeout is based on the CLOCK_REALTIME 

23933 clock; if the Timers option is not supported, the timeout is based on the system clock as returned 

23934 by the time( ) function. The resolution of the timeout is the resolution of the clock on which it is 

23935 based. The tiviespec argument is defined as a structure in the <time.h> header. 

23936 Under no circumstance shall the operation fail with a timeout if there is sufficient room in the 

23937 queue to add the message immediately. The validity of the absjivieout parameter need not be 

23938 checked when there is sufficient room in the queue. 


#include <mqueue.h> 

#include <time.h> 

int mq_timedsend(mqd_t mqdes, const char *msg_ptr, size_t msg_len, 
unsigned int msg_prio, const struct timespec * abs_timeout ); 


int mq_send(mqd_t mqdes, const char *msg_ptr, size_t msg_len, 
unsigned int msg_prio) ; 
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23939 RETURN VALUE 

23940 tmo Upon successful completion, the mq_send () and mqjtimedsend () functions shall return a value of I 

23941 zero. Otherwise, no message shall be enqueued, the functions shall return -1, and errno shall be I 

23942 set to indicate the error. 

23943 ERRORS 

23944 tmo The mq_send( ) and mq_timedsend{) functions shall fail if: I 

23945 [EAGAIN] The 0_N0NBL0CK flag is set in the message queue description associated 

23946 with mqdes, and the specified message queue is full. 

23947 [EBADF] The mqdes argument is not a valid message queue descriptor open for writing. 

23948 tmo [EINTR] A signal interrupted the call to mq_send( ) or mq_timedsend (). I 

23949 [EINVAL] The value of msg_prio was outside the valid range. I 

23950 tmo [EINVAL] The thread would have blocked, and the abs_timeout parameter specified a I 

23951 nanoseconds field value less than zero or greater than or equal to 1000 I 

23952 million. I 

23953 [EMSGSIZE] The specified message length, msgjen, exceeds the message size attribute of 

23954 the message queue. I 

23955 tmo [ETIMEDOUT] The 0_NONBLOCK flag was not set when the message queue was opened, I 

23956 but the timeout expired before the message could be enqueued. I 

23957 EXAMPLES 

23958 None. 

23959 APPLICATION USAGE 

23960 The value of the symbol |MQ_PRIO_MAX[ limits the number of priority levels supported by the 

23961 application. Message priorities range from 0 to {MQ_PRIO_MAX}-l. 

23962 RATIONALE 

23963 None. 

23964 FUTURE DIRECTIONS 

23965 None. 

23966 SEE ALSO 

23967 mqjopen (), mq_receive( ), mq_setattr( ), mqjtimedreceive (), time( ), the System Interface Definitions I 

23968 volume of IEEE Std. 1003.1-200x, <mqueue.h>, <time.h> I 

23969 CHANGE HISTORY 

23970 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 

23971 Issue 6 

23972 The mq_send( ) function is marked as part of the _POSIX_MESSAGE_PASSING option. 

23973 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

23974 implementation does not support the _POSIX_MESSAGE_PASSING option. I 

23975 The mq_timedsend () function is added for alignment with IEEE Std. 1003.1d-1999. I 


760 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


mq_setattr() 


23976 NAME 

23977 mq_setattr — set message queue attributes (REALTIME) 

23978 SYNOPSIS 

23979 MSG tinclude <mqueue.h> 

23980 int mq_setattr (mqd_t mqdes, const struct mq_attr *mqstat, 

23981 struct mq_attr * omqstat) ; 

23982 

23983 DESCRIPTION 

23984 The mq_setattr() function is used to set attributes associated with the open message queue 

23985 description referenced by the message queue descriptor specified by mqdes. 

23986 The message queue attributes corresponding to the following members defined in the mq_attr 

23987 structure are set to the specified values upon successful completion of mq_setattr (): 

23988 mqjtags The value of this member is the bitwise-logical OR of zero or more of 

23989 0_N0NBL0CK and any implementation-dependent flags. 

23990 The values of the mq_maxmsg, mq_msgsize, and mq_cnrmsgs members of the mq_attr structure are 

23991 ignored by mq_setattr (). 

23992 If omqstat is non-NULL, the mq_setattr( ) function stores, in the location referenced by omqstat, the 

23993 previous message queue attributes and the current queue status. These values are the same as 

23994 would be returned by a call to mq_getattr( ) at that point. 

23995 RETURN VALUE 

23996 Upon successful completion, the function shall return a value of zero and the attributes of the 

23997 message queue shall have been changed as specified. 

23998 Otherwise, the message queue attributes shall be unchanged, and the function shall return a 

23999 value of -1 and set errno to indicate the error. 

24000 ERRORS 

24001 The mq_setattr( ) function shall fail if: 

24002 [EBADF] The mqdes argument is not a valid message queue descriptor. 

24003 EXAMPLES 

24004 None. 

24005 APPLICATION USAGE 

24006 None. 

24007 RATIONALE 

24008 None. 

24009 FUTURE DIRECTIONS 

24010 None. 

24011 SEE ALSO 

24012 mq_open (), mq_send(), mq_timedsend {), msgctl(), msgget (), msgrcv (), msgsnd( ), the System I 

24013 Interface Definitions volume of IEEE Std. 1003.1-200x, <mqueue.h> 

24014 CHANGE HISTORY 

24015 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 
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24016 

24017 

24018 

24019 

24020 

24021 


Issue 6 

The mq_setattr () function is marked as part of the _POSIX_MESSAGE_PASSING option. 

The [ENOSYS] error condition has been removed as stubs need not be provided if an 
implementation does not support the _POSIX_MESSAGE_PASSING option. I 

The mq_timedsend () function is added to the SEE ALSO section for alignment with I 
IEEE Std. 1003.1d-1999. I 


762 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


mq_timedreceive() 


24022 NAME 

24023 mq_timedreceive — receive a message from a message queue (REALTIME) 

24024 SYNOPSIS 

24025 MSG TMO #include <mqueue.h> 

24026 tinclude <time.h> 

24027 int mq_timedreceive (mqd_t mqdes, char *msg_ptr, size_t msg_len, 

24028 unsigned int *msg_prio, const struct timespec * abs_timeout) ; 

24029 

24030 DESCRIPTION 

24031 Refer to mq_receive(). 
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24032 NAME 

24033 mq_timedsend — send a message to a message queue (REALTIME) 

24034 SYNOPSIS 

24035 MSG TMO #include <mqueue.h> 

24036 tinclude <time.h> 

24037 int mq_timedsend (mqd_t mqdes, const char *msg_ptr, size_t msg_len, 

24038 unsigned int msg_prio, const struct timespec * abs_timeout) ; 

24039 

24040 DESCRIPTION 

24041 Refer to mq_send{). 
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24042 NAME 

24043 mq_unlink — remove a message queue (REALTIME) 

24044 SYNOPSIS 

24045 MSG tinclude <mqueue.h> 

24046 int mq_unlink (const char * name) ; 

24047 

24048 DESCRIPTION 

24049 The mq_unlink( ) function shall remove the message queue named by the path name name. After 

24050 a successful call to mq_unlink{ ) with name, a call to mqjopen () with name fails if the flag 

24051 0_CREAT is not set in flags. If one or more processes have the message queue open when 

24052 mq_unlink( ) is called, destruction of the message queue is postponed until all references to the 

24053 message queue have been closed. Calls to mq_open () to recreate the message queue may fail until 

24054 the message queue is actually removed. However, the mq_unlink( ) call need not block until all 

24055 references have been closed; it may return immediately. 

24056 RETURN VALUE 

24057 Upon successful completion, the function shall return a value of zero. Otherwise, the named 

24058 message queue shall be unchanged by this function call, and the function shall return a value of 

24059 -1 and set errno to indicate the error. 

24060 ERRORS 

24061 The mq_unlink( ) function shall fail if: 

24062 [EACCES] Permission is denied to unlink the named message queue. 

24063 [ENAMETOOLONG] 

24064 The length of the name string exceeds |NAME_MAX} while 

24065 _POSIX_NO_TRUNC is in effect. 

24066 [ENOENT] The named message queue does not exist. 

24067 EXAMPLES 

24068 None. 

24069 APPLICATION USAGE 

24070 None. 

24071 RATIONALE 

24072 None. 

24073 FUTURE DIRECTIONS 

24074 None. 

24075 SEE ALSO 

24076 mq_close(), mq_open(), msgctl(), msgget(), msgrcv (), msgsnd( ), the System Interface Definitions 

24077 volume of IEEE Std. 1003.1-200x, <mqueue.h> 

24078 CHANGE HISTORY 

24079 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

24080 Issue 6 

24081 The mq_unlink( ) function is marked as part of the _POSIX_MESSAGE_PASSING option. 

24082 The Open Group corrigenda item U021 /5 has been applied, clarifying that upon unsuccessful 

24083 completion, the named message queue is unchanged by this function. 

24084 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

24085 implementation does not support the _POSIX_MESSAGE_PASSING option. 
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24086 NAME 

24087 mrand48 — generate uniformly distributed pseudo-random signed long integers 

24088 SYNOPSIS 

24089 xsi tinclude <stdlib.h> 

24090 long int mrand48 (void) ; 

24091 

24092 DESCRIPTION 

24093 Refer to drand48 (). 
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24094 NAME 

24095 msgctl — XSI message control operations 

24096 SYNOPSIS 

24097 XSI tinclude <sys/msg.h> 

24098 int msgctl (int msqid, int cmd, struct msqid_ds *buf) ; 

24099 


24100 DESCRIPTION 

24101 The msgctl () function operates on XSI message queues (see the System Interface Definitions I 

24102 volume of IEEE Std. 1003.1-200x, Section 3.438, XSI Message Queue). It is unspecified whether I 

24103 this function interoperates with the realtime interprocess communication facilities defined in 

24104 Section 2.8 on page 59. 

24105 The msgctl () function shall provide message control operations as specified by cmd. The 

24106 following values for cmd, and the message control operations they specify, are: 


24107 

24108 

24109 


IPC_STAT Place the current value of each member of the msqid_ds data structure 

associated with msqid into the structure pointed to by buf. The contents of this 
structure are defined in <sys/msg.h>. 


24110 

24111 

24112 


IPC_SET Set the value of the following members of the msqid_ds data structure 

associated with msqid to the corresponding value found in the structure 
pointed to by buf: 


24113 

24114 

24115 

24116 


msg_perm.uid 
msg_perm.gid 
msg_perm.mode 
msg_qbytes 


24117 

24118 

24119 

24120 


IPC_SET can only be executed by a process with appropriate privileges or that 
has an effective user ID equal to the value of msg_perm.cuid or 
msg_perm.uid in the msqid_ds data structure associated with msqid. Only a 
process with appropriate privileges can raise the value of msg_qbytes. 


24121 

24122 

24123 

24124 

24125 


IPC_RMID Remove the message queue identifier specified by msqid from the system and 

destroy the message queue and msqid_ds data structure associated with it. 
IPC_RMD can only be executed by a process with appropriate privileges or 
one that has an effective user ID equal to the value of msg_perm.cuid or 
msg_perm.uid in the msqid_ds data structure associated with msqid. 


24126 RETURN VALUE 

24127 Upon successful completion, msgctl () shall return 0; otherwise, it shall return -1 and set errno to 

24128 indicate the error. 


24129 ERRORS 

24130 The msgctl () function shall fail if: 


24131 

24132 


[EACCES] The argument cmd is IPC_STAT and the calling process does not have read 

permission; see Section 2.7 on page 57. 


24133 

24134 


[EINVAL] 


The value of msqid is not a valid message queue identifier; or the value of cmd 
is not a valid command. 


24135 

24136 

24137 

24138 


[EPERM] The argument cmd is IPC_RMID or IPC_SET and the effective user ID of the 

calling process is not equal to that of a process with appropriate privileges 
and it is not equal to the value of msg_perm.cuid or msg_perm.uid in the data 
structure associated with msqid. 
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24139 [EPERM] The argument and is IPC_SET, an attempt is being made to increase to the 

24140 value of msg_qbytes, and the effective user ID of the calling process does not 

24141 have appropriate privileges. 

24142 EXAMPLES 

24143 None. 

24144 APPLICATION USAGE 

24145 The POSIX Realtime Extension defines alternative interfaces for interprocess communication 

24146 (IPC). Application developers who need to use IPC should design their applications so that 

24147 modules using the IPC routines described in Section 2.7 on page 57 can be easily modified to use 

24148 the alternative interfaces. 

24149 RATIONALE 

24150 None. 

24151 FUTURE DIRECTIONS 

24152 None. 

24153 SEE ALSO 

24154 mq_close(), mq_getattr(), mq_notify(), mq_open (), mq_receive(), mq_send(), mq_setattr(), 

24155 mq_unlink(), msgget(), msgrcv (), msgsnd (), the System Interface Definitions volume of 

24156 IEEE Std. 1003.1-200x, <sys/msg.h>. Section 2.7 on page 57 

24157 CHANGE HISTORY 

24158 First released in Issue 2. 

24159 Derived from Issue 2 of the SVID. 

24160 Issue 4 

24161 The function is no longer marked as OPTIONAL FUNCTIONALITY. 

24162 Inclusion of the <sys/types.h> and <sys/ipc.h> headers is removed from the SYNOPSIS section. 

24163 A FUTURE DIRECTIONS section is added warning application developers about migration to 

24164 IEEE 1003.4 interfaces for interprocess communication. 

24165 The [ENOSYS] error is removed from the ERRORS section. 

24166 Issue 5 

24167 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 

24168 DIRECTIONS to a new APPLICATION USAGE section. 


System Interfaces, Issue 6 


769 



msggetO 


System Interfaces 


24169 

24170 

24171 

24172 

24173 

24174 

24175 

24176 

24177 

24178 

24179 

24180 

24181 

24182 

24183 

24184 

24185 

24186 

24187 

24188 

24189 

24190 

24191 

24192 

24193 

24194 

24195 

24196 

24197 

24198 

24199 

24200 

24201 

24202 

24203 

24204 

24205 

24206 

24207 

24208 

24209 


NAME 

msgget — get the XSI message queue identifier 

SYNOPSIS 

xsi tinclude <sys/msg.h> 

int msgget(key_t key, int msgflg ) ; 


DESCRIPTION 

The msgget () function operates on XSI message queues (see the System Interface Definitions I 
volume of IEEE Std. 1003.1-200x, Section 3.438, XSI Message Queue). It is unspecified whether I 
this function interoperates with the realtime interprocess communication facilities defined in 
Section 2.8 on page 59. 

The msgget () function shall return the message queue identifier associated with the argument 
key. 

A message queue identifier, associated message queue, and data structure (see <sys/msg.h>), are 
created for the argument key if one of the following is true: 

• The argument key is equal to IPC_PRIVATE. 

• The argument key does not already have a message queue identifier associated with it, and 
(i msgflg & IPC_CREAT) is non-zero. 

Upon creation, the data structure associated with the new message queue identifier is initialized 
as follows: 


• msg_perm.cuid, msg_perm.uid, msg_perm.cgid, and msg_perm.gid are set equal to the 
effective user ID and effective group ID, respectively, of the calling process. 

• The low-order 9 bits of msg_perm.mode are set equal to the low-order 9 bits of msgflg. 

• msg_qnum, msgjspid, msgjrpid, msg_stime, and msg_rtime are set equal to 0. 

• msg_ctime is set equal to the current time. 

• msg_qbytes is set equal to the system limit. 

RETURN VALUE 

Upon successful completion, msgget () shall return a non-negative integer, namely a message 
queue identifier. Otherwise, it shall return -1 and set errno to indicate the error. 


ERRORS 

The msgget () function shall fail if: 


[EACCES] 


[EEXIST] 

[ENOENT] 

[ENOSPC] 


A message queue identifier exists for the argument key, but operation 
permission as specified by the low-order 9 bits of msgflg would not be granted; 
see Section 2.7 on page 57. 

A message queue identifier exists for the argument key but (( msgflg & 
IPC_CREAT) && ( msgflg & IPC_EXCL)) is non-zero. 

A message queue identifier does not exist for the argument key and (msgflg & 
IPC_CREAT) is 0. 

A message queue identifier is to be created but the system-imposed limit on 
the maximum number of allowed message queue identifiers system-wide 
would be exceeded. 
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24210 

24211 

24212 

24213 

24214 

24215 

24216 

24217 

24218 

24219 

24220 

24221 

24222 

24223 

24224 

24225 

24226 

24227 

24228 

24229 

24230 

24231 

24232 

24233 

24234 


EXAMPLES 

None. 

APPLICATION USAGE 

The POSIX Realtime Extension defines alternative interfaces for interprocess communication 
(IPC). Application developers who need to use IPC should design their applications so that 
modules using the IPC routines described in Section 2.7 on page 57 can be easily modified to use 
the alternative interfaces. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

mq_close(), mq_getattr(), mq_notify(), mq_open (), mq_receive(), mq_send(), mq_setattr(), 
mq_unlink( ), msgctl(), msgrcv(), msgsnd(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <sys/msg.h>. Section 2.7 on page 57 

CHANGE HISTORY 

First released in Issue 2. 

Derived from Issue 2 of the SVID. 


Issue 4 

The function is no longer marked as OPTIONAL FUNCTIONALITY. 

Inclusion of the <sys/types.h> and <sys/ipc.h> headers is removed from the SYNOPSIS section. 
The [ENOSYS] error is removed from the ERRORS section. 

Issue 5 

The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 
DIRECTIONS to a new APPLICATION USAGE section. 
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24235 NAME 

24236 msgrcv — XSI message receive operation 

24237 SYNOPSIS 

24238 XSI #include <sys/msg.h> 

24239 

24240 

24241 

24242 DESCRIPTION 

24243 The msgrcv () function operates on XSI message queues (see the System Interface Definitions I 

24244 volume of IEEE Std. 1003.1-200x, Section 3.438, XSI Message Queue). It is unspecified whether I 

24245 this function interoperates with the realtime interprocess communication facilities defined in 

24246 Section 2.8 on page 59. 

24247 The msgrcv ( ) function shall read a message from the queue associated with the message queue 

24248 identifier specified by msqid and place it in the user-defined buffer pointed to by msgp . 

24249 The application shall ensure that the argument msgp points to a user-defined buffer that contains I 

24250 first a field of type long int specifying the type of the message, and then a data portion that I 

24251 holds the data bytes of the message. The structure below is an example of what this user-defined I 

24252 buffer might look like: I 

24253 struct mymsg { 

24254 long int mtype; /* Message type. */ 

24255 char mtext [1]; /* Message text. */ 

24256 } 

24257 

24258 

24259 

24260 

24261 

24262 

24263 

24264 

24265 

24266 

24267 

24268 

24269 

24270 

24271 

24272 

24273 

24274 

24275 

24276 
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The structure member mtype is the received message's type as specified by the sending process. 
The structure member mtext is the text of the message. 

The argument msgsz specifies the size in bytes of mtext. The received message is truncated to 
msgsz bytes if it is larger than msgsz and ( msgflg & MSG_NOERROR) is non-zero. The truncated 
part of the message is lost and no indication of the truncation is given to the calling process. 

If the value of msgsz is greater than |SSIZE_MAX}, the result is implementation-dependent. 

The argument msgtyp specifies the type of message requested as follows: 

• If msgtyp is 0, the first message on the queue is received. 

• If msgtyp is greater than 0, the first message of type msgtyp is received. 

• If msgtyp is less than 0, the first message of the lowest type that is less than or equal to the 
absolute value of msgtyp is received. 

The argument msgflg specifies the action to be taken if a message of the desired type is not on the 
queue. These are as follows: 

• If ( msgflg & IPC_NOWAIT) is non-zero, the calling thread shall return immediately with a 
return value of -1 and errno set to [ENOMSG]. 

• If ( msgflg & IPC_NOWAIT) is 0, the calling thread shall suspend execution until one of the 
following occurs: 

— A message of the desired type is placed on the queue. 

— The message queue identifier msqid is removed from the system; when this occurs, errno 
shall be set equal to [EIDRM] and -1 shall be returned. 


ssize_t msgrcv(int msqid, void *msgp, size_t msgsz, long int msgtyp, 
int msgflg) ; 
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24278 

24279 

24280 

24281 

24282 

24283 

24284 

24285 

24286 

24287 

24288 

24289 

24290 

24291 

24292 

24293 

24294 

24295 

24296 

24297 

24298 

24299 

24300 

24301 

24302 

24303 

24304 

24305 

24306 

24307 

24308 

24309 

24310 

24311 

24312 

24313 

24314 

24315 

24316 


— The calling thread receives a signal that is to be caught; in this case a message is not 
received and the calling thread resumes execution in the manner prescribed in sigaction (). 

Upon successful completion, the following actions are taken with respect to the data structure 
associated with msqid: 

• msg_qnum is decremented by 1. 

• msg_lrpid is set equal to the process ID of the calling process. 

• msg_rtime is set equal to the current time. 

RETURN VALUE 

Upon successful completion, msgrcv( ) shall return a value equal to the number of bytes actually 
placed into the buffer mtext. Otherwise, no message shall be received, msgrcv{) shall return 
(ssize_t)-l, and errno shall be set to indicate the error. 


ERRORS 

The msgrcv( ) function shall fail if: 

[E2BIG] The value of mtext is greater than msgsz and ( msgflg & MSG_NOERROR) is 0. 

[EACCES] Operation permission is denied to the calling process; see Section 2.7 on page 

57. 


[EIDRM] 

[EINTR] 

[EINVAL] 

[ENOMSG] 


The message queue identifier msqid is removed from the system. 

The msgrcv( ) function was interrupted by a signal. 
msqid is not a valid message queue identifier. 

The queue does not contain a message of the desired type and ( msgflg & 
IPC_NOWAIT) is non-zero. 


EXAMPLES 


Receiving a Message 

The following example receives the first message on the queue (based on the value of the 
msgtype argument, 0). The queue is identified by the msqid argument (assuming that the value 
has previously been set). This call specifies that an error should be reported if no message is 
available, but not if the message is too large. The message size is calculated directly using the 
sizeof operator. 

#include <sys/msg.h> 

int result; 
int msqid; 
struct message { 
long type; 
char text [20]; 

} msg; 

long msgtyp = 0; 

result = msgrcv (msqid, (void *) &msg, sizeof (msg.text), 
msgtyp, MSG_NOERROR | IPC_NOWAIT); 
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24317 APPLICATION USAGE 

24318 The POSIX Realtime Extension defines alternative interfaces for interprocess communication 

24319 (IPC). Application developers who need to use IPC should design their applications so that 

24320 modules using the IPC routines described in Section 2.7 on page 57 can be easily modified to use 

24321 the alternative interfaces. 

24322 RATIONALE 

24323 None. 

24324 FUTURE DIRECTIONS 

24325 None. 

24326 SEE ALSO 

24327 mq_close(), mq_getattr(), mq_notify(), mq_open (), mq_receive(), mq_send(), mq_setattr(), 

24328 mq_unlink( ), msgctl (), msgget (), msgsnd( ), sigaction (), the System Interface Definitions volume of 

24329 IEEE Std. 1003.1-200x, <sys/msg.h>. Section 2.7 on page 57 

24330 CHANGE HISTORY 

24331 First released in Issue 2. 

24332 Derived from Issue 2 of the SVID. 

24333 Issue 4 

24334 The function is no longer marked as OPTIONAL FUNCTIONALITY. 

24335 Inclusion of the <sys/types.h> and <sys/ipc.h> headers is removed from the SYNOPSIS section. 

24336 The [ENOSYS] error is removed from the ERRORS section. 

24337 A FUTURE DIRECTIONS section is added warning application developers about migration to 

24338 IEEE 1003.4 interfaces for interprocess communication. 

24339 Issue 5 

24340 The type of the return value is changed from int to ssize_t, and a warning is added to the 

24341 DESCRIPTION about values of msgsz larger the {SSIZE_MAX}. 

24342 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 

24343 DIRECTIONS to the APPLICATION USAGE section. 

24344 Issue 6 

24345 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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24346 NAME 

24347 msgsnd — XSI message send operation 

24348 SYNOPSIS 

24349 XSI tinclude <sys/msg.h> 

24350 int msgsnd (int msqid, const void *msgp, size_t msgsz, int msgflg) ; 

24351 

24352 DESCRIPTION 

24353 The msgsnd() function operates on XSI message queues (see the System Interface Definitions I 

24354 volume of IEEE Std. 1003.1-200x, Section 3.438, XSI Message Queue). It is unspecified whether I 

24355 this function interoperates with the realtime interprocess communication facilities defined in 

24356 Section 2.8 on page 59. 

24357 The msgsndO function is used to send a message to the queue associated with the message 

24358 queue identifier specified by msqid. 

24359 The application shall ensure that the argument msgp points to a user-defined buffer that contains I 

24360 first a field of type long int specifying the type of the message, and then a data portion that I 

24361 holds the data bytes of the message. The structure below is an example of what this user-defined I 

24362 buffer might look like: I 

24363 struct mymsg { 

24364 long int mtype; /* Message type. */ 

24365 char mtextfl]; /* Message text. */ 

24366 } 

24367 The structure member mtype is a non-zero positive type long int that can be used by the 

24368 receiving process for message selection. 

24369 The structure member mtext is any text of length msgsz bytes. The argument msgsz can range 

24370 from 0 to a system-imposed maximum. 

24371 The argument msgflg specifies the action to be taken if one or more of the following are true: 

24372 • The number of bytes already on the queue is equal to msg_qbytes ; see <sys/msg.h>. 

24373 • The total number of messages on all queues system-wide is equal to the system-imposed 

24374 limit. 

24375 These actions are as follows: 

24376 • If ( msgflg & IPC_NOWAIT) is non-zero, the message shall not be sent and the calling thread 

24377 shall return immediately. 

24378 • If ( msgflg & IPC_NOWAIT) is 0, the calling thread shall suspend execution until one of the 

24379 following occurs: 

24380 — The condition responsible for the suspension no longer exists, in which case the message 

24381 is sent. 

24382 — The message queue identifier msqid is removed from the system; when this occurs, errno 

24383 shall be set equal to [EIDRM] and -1 shall be returned. 

24384 — The calling thread receives a signal that is to be caught; in this case the message is not 

24385 sent and the calling thread resumes execution in the manner prescribed in sigaction (). 

24386 Upon successful completion, the following actions are taken with respect to the data structure 

24387 associated with msqid ; see <sys/msg.h>: 
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24388 

24389 

24390 

24391 

24392 

24393 

24394 

24395 

24396 

24397 

24398 

24399 

24400 

24401 

24402 

24403 

24404 

24405 

24406 

24407 

24408 

24409 

24410 

24411 

24412 

24413 

24414 

24415 

24416 

24417 

24418 

24419 

24420 

24421 

24422 

24423 

24424 

24425 

24426 

24427 


• msg_qnum is incremented by 1. 

• msgjspid is set equal to the process ID of the calling process. 

• msg_stime is set equal to the current time. 

RETURN VALUE 

Upon successful completion, msgsnd( ) shall return 0; otherwise, no message shall be sent, 
msgsnd( ) shall return -1, and err no shall be set to indicate the error. 


ERRORS 


The msgsnd( ) function shall fail if: 

[EACCES] Operation permission is denied to the calling process; see Section 2.7 on page 


57. 


[EAGAIN] 

[EIDRM] 

[EINTR] 

[EINVAL] 

EXAMPLES 


The message cannot be sent for one of the reasons cited above and (msgflg & 
IPC_NOWAIT) is non-zero. 

The message queue identifier msgid is removed from the system. 

The msgsnd() function was interrupted by a signal. 

The value of msqid is not a valid message queue identifier, or the value of 
mtype is less than 1; or the value of rrisgsz is less than 0 or greater than the 
system-imposed limit. 


Sending a Message 

The following example sends a message to the queue identified by the msqid argument 
(assuming that value has previously been set). This call specifies that an error should be 
reported if no message is available. The message size is calculated directly using the sizeof 
operator. 

#include <sys/msg.h> 

int result; 
int msqid; 
struct message { 
long type; 
char text[20]; 

} msg; 

msg.type = 1; 

strcpy (msg.text, "This is message 1"); 

result = msgsnd (msqid, (void *) &msg, sizeof (msg.text), IPC_NOWAIT); 

APPLICATION USAGE 

The POSIX Realtime Extension defines alternative interfaces for interprocess communication 
(IPC). Application developers who need to use IPC should design their applications so that 
modules using the IPC routines described in Section 2.7 on page 57 can be easily modified to use 
the alternative interfaces. 
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24428 RATIONALE 

24429 None. 

24430 FUTURE DIRECTIONS 

24431 None. 

24432 SEE ALSO 

24433 mq_close(), mq_getattr(), mq_notify(), mq_open (), mq_receive(), mq_send(), mq_setattr(), 

24434 mq_unlink (), msgctl (), msgget (), msgrcv (), sigaction (), the System Interface Definitions volume of 

24435 IEEE Std. 1003.1-200x, <sys/msg.h>. Section 2.7 on page 57 

24436 CHANGE HISTORY 

24437 First released in Issue 2. 

24438 Derived from Issue 2 of the SVID. 

24439 Issue 4 

24440 The function is no longer marked as OPTIONAL FUNCTIONALITY. 

24441 Inclusion of the <sys/types.h> and <sys/ipc.h> headers is removed from the SYNOPSIS section. 

24442 Also the type of argument msgp is changed from void 51 ' to const void 51 '. 

24443 In the DESCRIPTION, the example of a message buffer is changed: 

24444 • Explicitly to define the first member as being of type long int 

24445 • To define the size of the message array mtext 

24446 The [ENOSYS] error is removed from the ERRORS section. 

24447 A FUTURE DIRECTIONS section is added warning application developers about migration to 

24448 IEEE 1003.4 interfaces for interprocess communication. 

24449 Issue 5 

24450 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 

24451 DIRECTIONS to a new APPLICATION USAGE section. 

24452 Issue 6 

24453 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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24454 NAME 

24455 msync — synchronize memory with physical storage 

24456 SYNOPSIS 

24457 mf SIO #include <sys/mman.h> 

24458 int msync (void *addr, size_t len, int flags) ; 

24459 


24460 DESCRIPTION 


24461 

24462 

24463 

24464 


The msync() function shall write all modified data to permanent storage locations, if any, in 
those whole pages containing any part of the address space of the process starting at address 
nddr and continuing for len bytes. If no such storage exists, msync () need not have any effect. If 
requested, the msync () function then invalidates cached copies of data. 


24465 man The implementation shall require that ciddr be a multiple of the page size as returned by 

24466 sysconf(). 


24467 

24468 

24469 

24470 

24471 

24472 SHMITYM 

24473 


For mappings to files, the msync () function ensures that all write operations are completed as 
defined for synchronized I/O data integrity completion. It is unspecified whether the 
implementation also writes out other file attributes. When the msync() function is called on 
MAP_PRIVATE mappings, any modified data shall not be written to the underlying object and 
shall not cause such data to be made visible to other processes. It is unspecified whether data in 
MAP_PRIVATE mappings has any permanent storage locations. The effect of msync() on a 
shared memory object or a typed memory object is unspecified. 


24474 

24475 

24476 

24477 

24478 

24479 

24480 


Th e flags argument is constructed from the bitwise-inclusive OR of one or more of the following 
flags defined in the header <sys/mman.h>: 


Symbolic Constant 

Description 

MS_ASYNC 

MS_SYNC 

MSJNVALIDATE 

Perform asynchronous writes. 
Perform synchronous writes. 
Invalidate cached data. 


24481 When MS_ASYNC is specified, msync( ) shall return immediately once all the write operations 

24482 are initiated or queued for servicing; when MS_SYNC is specified, msync () shall not return until 

24483 all write operations are completed as defined for synchronized I/O data integrity completion. 

24484 Either MS_ASYNC or MS_SYNC is specified, but not both. 

24485 When MS_INVALIDATE is specified, msync () invalidates all cached copies of mapped data that 

24486 are inconsistent with the permanent storage locations such that subsequent references shall 

24487 obtain data that was consistent with the permanent storage locations sometime between the call 

24488 to msync{ ) and the first subsequent memory reference to the data. 

24489 The behavior of this function is unspecified if the mapping was not established by a call to 

24490 mmap(). 

24491 If msync( ) causes any write to a file, the file's stjctime and st_mtime fields shall be marked for 

24492 update. 

24493 RETURN VALUE 

24494 Upon successful completion, msync( ) shall return 0; otherwise, it shall return -1 and set errno to 

24495 indicate the error. 
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24534 
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ERRORS 

The msync( ) function shall fail if: 

man [EBUSY] Some or all of the addresses in the range starting at addr and continuing for len 

bytes are locked, and MS_IN VALID ATE is specified. 

[EINVAL] The value in flags is invalid. 

man [EINVAL] The value of addr is not a multiple of the page size, {PAGESIZE}. 

[ENOMEM] The addresses in the range starting at addr and continuing for len bytes are 
outside the range allowed for the address space of a process or specify one or 
more pages that are not mapped. 

EXAMPLES 

None. 

APPLICATION USAGE 

The msync() function is only supported if the _POSIX_MAPPED_FILES option and the 
_POSIX_SYNCHRONIZED_IO option are supported, and thus need not be available on all 
implementations. 

The msync() function should be used by programs that require a memory object to be in a 
known state; for example, in building transaction facilities. 

Normal system activity can cause pages to be written to disk. Therefore, there are no guarantees 
that msync( ) is the only control over when pages are or are not written to disk. 

RATIONALE 

The msync( ) function is used to write out data in a mapped region to the permanent storage for 
the underlying object. The call to msync( ) ensures data integrity of the file. 

After the data is written out, any cached data may be invalidated if the MS_INVALIDATE flag 
was specified. This is useful on systems that do not support read/write consistency. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

mmap (), sysconf(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

<sys/mman.h> 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 

Aligned with msync( ) in the POSIX Realtime Extension as follows: 

• The DESCRIPTION is extensively reworded. 

• [EBUSY] and a new form of [EINVAL] are added as mandatory error conditions. 

Issue 6 

The msync{) function is marked as part of the _POSIX_MAPPED_FILES and 
_POSIX_SYNCHRONIZED_IO options. 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [EBUSY] mandatory error condition is added. 
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24537 

24538 

24539 

24540 

24541 

24542 

24543 


The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The DESCRIPTION is updated to state that implementations require nddr to be a multiple of 
the page size. 

• The second [EINVAL] error condition is made mandatory. 

The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by adding reference to I 
typed memory objects. I 
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24544 NAME 

24545 munlock — unlock a range of process address space 

24546 SYNOPSIS 

24547 MLR #include <sys/mman.h> 

24548 int munlock (const void * addr, size_t len) ; 

24549 

24550 DESCRIPTION 

24551 Refer to mlock (). 
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24552 NAME 

24553 munlockall — unlock the address space of a process 

24554 SYNOPSIS 

24555 ml #include <sys/mman.h> 

24556 int munlockall (void) ; 

24557 

24558 DESCRIPTION 

24559 Refer to mlockall(). 
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24560 NAME 

24561 munmap — unmap pages of memory 

24562 SYNOPSIS 

24563 mfishm #include <sys/mman.h> 

24564 int munmap (void *adc?r, size_t Jen); 

24565 

24566 DESCRIPTION 

24567 The munmap{ ) function shall remove any mappings for those entire pages containing any part of 

24568 the address space of the process starting at addr and continuing for ten bytes. Further references 

24569 to these pages result in the generation of a SIGSEGV signal to the process. If there are no 

24570 mappings in the specified address range, then munmap {) has no effect. 

24571 man The implementation shall requirethat addr be a multiple of the page size {PAGESIZE}. 

24572 If a mapping to be removed was private, any modifications made in this address range shall be 

24573 discarded. 

24574 ml i mlr Any memory locks (see mlock() and mlockall()) associated with this address range shall be I 

24575 removed, as if by an appropriate call to munlock (). 

24576 tym If a mapping removed from a typed memory object causes the corresponding address range of I 

24577 the memory pool to be inaccessible by any process in the system except through allocatable I 

24578 mappings (that is, mappings of typed memory objects opened with the I 

24579 POSIX_TYPED_MEM_MAP_ALLOCATABLE flag), then that range of the memory pool shall I 

24580 become deallocated and may become available to satisfy future typed memory allocation I 

24581 requests. I 

24582 A mapping removed from a typed memory object opened with the I 

24583 POSIX_TYPED_MEM_MAP_ALLOCATABLE flag shall not affect in any way the availability of I 

24584 that typed memory for allocation. I 

24585 The behavior of this function is unspecified if the mapping was not established by a call to I 

24586 nitnapi ). 

24587 RETURN VALUE 

24588 Upon successful completion, munmap{) shall return 0; otherwise, it shall return -1 and set err no 

24589 to indicate the error. 

24590 ERRORS 

24591 The mnnmap( ) function shall fail if: 

24592 [EINVAL] Addresses in the range [addr,addr+len) are outside the valid range for the 

24593 address space of a process. 

24594 man [EINVAL] The ten argument is 0. 

24595 man [EINVAL] The addr argument is not a multiple of the page size as returned by sysconf( ). 
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24596 EXAMPLES 

24597 None. 

24598 APPLICATION USAGE 

24599 The munmap () function is only supported if the _POSIX_MAPPED_FILES option or the 

24600 _POSIX_SHARED_MEMORY_OBJECTS option is supported. 

24601 RATIONALE 

24602 The munmapO function corresponds to SVR4, just as the nimap () function does. 

24603 It is possible that an application has applied process memory locking to a region that contains 

24604 shared memory. If this has occurred, the munmap () call ignores those locks and, if necessary, 

24605 causes those locks to be removed. 

24606 FUTURE DIRECTIONS 

24607 None. 

24608 SEE ALSO 

24609 mlock (), mlockall (), mmap(), posix_typed_mem_open{), sysconf( ), the System Interface Definitions I 

24610 volume of IEEE Std. 1003.1-200x, <signal.h>, <sys/mman.h> 

24611 CHANGE HISTORY 

24612 First released in Issue 4, Version 2. 

24613 Issue 5 

24614 Moved from X/OPEN UNIX extension to BASE. 

24615 Aligned with munmap{ ) in the POSIX Realtime Extension as follows: 

24616 • The DESCRIPTION is extensively reworded. 

24617 • The SIGBUS error is no longer permitted to be generated. 

24618 Issue 6 

24619 The munmapO function is marked as part of the _POSIX_MAPPED_FILES and 

24620 _POSIX_SHARED_MEMORY_OBJECTS option. 

24621 The following new requirements on POSIX implementations derive from alignment with the 

24622 Single UNIX Specification: 

24623 • The DESCRIPTION is updated to state that implementations require addr to be a multiple of 

24624 the page size. 

24625 • The [EINVAL] error conditions are added. 

24626 The following changes are made for alignment with IEEE Std. 1003.1j-2000: I 

24627 • Semantics for typed memory objects are added to the DESCRIPTION. 

24628 • The posix_typed_mem_open () function is added to the SEE ALSO section. I 
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24629 NAME 

24630 nanosleep — high resolution sleep (REALTIME) 

24631 SYNOPSIS 

24632 tmr #include <time.h> 

24633 int nanosleep (const struct timespec *rqtp, struct timespec *rmtp) ; 

24634 

24635 DESCRIPTION 

24636 The nanosleep () function shall cause the current thread to be suspended from execution until 

24637 either the time interval specified by the rqtp argument has elapsed or a signal is delivered to the 

24638 calling thread, and its action is to invoke a signal-catching function or to terminate the process. 

24639 The suspension time may be longer than requested because the argument value is rounded up to 

24640 an integer multiple of the sleep resolution or because of the scheduling of other activity by the 

24641 system. But, except for the case of being interrupted by a signal, the suspension time shall not be 

24642 less than the time specified by rqtp, as measured by the system clock, CLOCK_REALTIME. 

24643 The use of the nanosleep () function has no effect on the action or blockage of any signal. 

24644 RETURN VALUE 

24645 If the nanosleep () function returns because the requested time has elapsed, its return value shall 

24646 be zero. 

24647 If the nanosleep () function returns because it has been interrupted by a signal, the function shall 

24648 return a value of -1 and set errno to indicate the interruption. If the rmtp argument is non-NULL, 

24649 the timespec structure referenced by it is updated to contain the amount of time remaining in 

24650 the interval (the requested time minus the time actually slept). If the rmtp argument is NULL, the 

24651 remaining time is not returned. 

24652 If nanosleep () fails, it shall return a value of -1 and set errno to indicate the error. 

24653 ERRORS 

24654 The nanosleep () function shall fail if: 

24655 [EINTR] The nanosleep {) function was interrupted by a signal. 

24656 [EINVAL] The rqtp argument specified a nanosecond value less than zero or greater than 

24657 or equal to 1000 million. 

24658 EXAMPLES 

24659 None. 

24660 APPLICATION USAGE 

24661 None. 

24662 RATIONALE 

24663 It is common to suspend execution of a process for an interval in order to poll the status of a 

24664 non-interrupting function. A large number of actual needs can be met with a simple extension to 

24665 sleep () that provides finer resolution. 

24666 In the POSIX.1-1990 standard and SVR4, it is possible to implement such a routine, but the 

24667 frequency of wakeup is limited by the resolution of the alarm () and sleep () functions. In 4.3 BSD, 

24668 it is possible to write such a routine using no static storage and reserving no system facilities. 

24669 Although it is possible to write a function with similar functionality to sleep () using the 

24670 remainder of the timers function, such a function requires the use of signals and the reservation 

24671 of some signal number. This volume of IEEE Std. 1003.1-200x requires that nanosleep () be non- 

24672 intrusive of the signals function. 
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24673 The nanosleep () function shall return a value of 0 on success and -1 on failure or if interrupted. 

24674 This latter case is different from sleep (). This was done because the remaining time is returned 

24675 via an argument structure pointer, rmtp, instead of as the return value. 

24676 FUTURE DIRECTIONS 

24677 None. 

24678 SEE ALSO 

24679 sleep (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <time.h> 

24680 CHANGE HISTORY 

24681 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

24682 Issue 6 

24683 The nanosleep () function is marked as part of the _POSIX_TIMERS option. 

24684 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

24685 implementation does not support the _POSIX_TIMERS option. 
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24686 

24687 

24688 

24689 

24690 

24691 

24692 

24693 

24694 

24695 

24696 

24697 

24698 

24699 

24700 

24701 

24702 

24703 

24704 

24705 

24706 

24707 

24708 

24709 

24710 

24711 

24712 

24713 

24714 

24715 

24716 

24717 

24718 

24719 

24720 

24721 

24722 


NAME 

nextafter — next representable double-precision floating-point number 

SYNOPSIS 

xsi tinclude <math.h> 

double nextafter(double x, double y) ; 

DESCRIPTION 

The nextafter () function shall compute the next representable double-precision floating-point 
value following x in the direction of y. Thus, if y is less than x, nextafter() returns the largest 
representable floating-point number less than x. 

An application wishing to check for error situations should set errno to 0 before calling 
nextafter (). If errno is non-zero on return, or the value NaN is returned, an error has occurred. 

RETURN VALUE 

The nextafter () function shall return the next representable double-precision floating-point value 
following x in the direction of y. 

If x or y is NaN, then nextafter () shall return NaN and may set errno to [EDOM], 

If x is finite and the correct function value would overflow, HUGE_VAL shall be returned and 
errno set to [ERANGE]. 

ERRORS 

The nextafter () function shall fail if: 

[ERANGE] The correct value would overflow. 

The nextafter () function may fail if: 

[EDOM] The x or y argument is NaN. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

The System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 
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24723 NAME 

24724 nftw — walk a file tree 

24725 SYNOPSIS 

24726 xsi #include <ftw.h> 

24727 int nftw (const char *path, int (* fn) (const char *, 

24728 const struct stat *, int, struct FTW *), int depth, int flags); 

24729 


24730 DESCRIPTION 

24731 

24732 

24733 


24734 

24735 

24736 

24737 

24738 

24739 

24740 

24741 

24742 

24743 

24744 

24745 

24746 

24747 

24748 

24749 


The nftw () function shall recursively descend the directory hierarchy rooted in path. The nftw () 
function has a similar effect to ftzv( ) except that it takes an additional argument flags, which is a 
bitwise-inclusive OR of zero or more of the following flags: 

FTW_CHDIR If set, nftw () shall change the current working directory to each directory as it 
reports files in that directory. If clear, nftzv () shall not change the current 
working directory. 

FTW_DEPTH If set, nftzv () shall report all files in a directory before reporting the directory 
itself. If clear, nftw () shall report any directory before reporting the files in that 
directory. 

FTW_MOUNT If set, nftzv() shall only report files in the same file system as path . If clear, 
nftw () shall report all files encountered during the walk. 

FTW_PHYS If set, nftw () shall perform a physical walk and shall not follow symbolic links. 

If FTW_PFIYS is clear and FTW_DEPTH is set, nftzv () shall follow links instead of reporting 
them, but shall not report any directory that would be a descendant of itself. If FTW_PHYS is 
clear and FTW_DEPTH is clear, nftw () shall follow links instead of reporting them, but shall not 
report the contents of any directory that would be a descendant of itself. 

At each file it encounters, nftzv () shall call the user-supplied function//; with four arguments: 

• The first argument is the path name of the object. 

• The second argument is a pointer to the stat buffer containing information on the object. 


24750 • The third argument is an integer giving additional information. Its value is one of the 


24751 

following: 


24752 

FTW_F 

The object is a file. 

24753 

FTW_D 

The object is a directory. 

24754 

24755 

FTW_DP 

The object is a directory and subdirectories have been visited. (This condition 
shall only occur if the FTW_DEPTH flag is included in flags .) 

24756 

24757 

FTW_SL 

The object is a symbolic link. (This condition shall only occur if the FTW_PFIYS 
flag is included in flags .) 

24758 

24759 

FTW_SLN 

The object is a symbolic link that does not name an existing file. (This 
condition shall only occur if the FTW_PHYS flag is not included in flags .) 

24760 

24761 

FTW_DNR 

The object is a directory that cannot be read. Th efn function shall not be called 
for any of its descendants. 

24762 

24763 

24764 

FTW_NS 

The stat() function failed on the object because of lack of appropriate 
permission. The stat buffer passed to fn is undefined. Failure of stat() for any 
other reason is considered an error and nftw () shall return -1. 
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24765 

24766 

24767 

24768 

24769 

24770 

24771 

24772 

24773 

24774 

24775 

24776 

24777 

24778 

24779 

24780 

24781 

24782 

24783 

24784 

24785 

24786 

24787 

24788 

24789 

24790 

24791 

24792 

24793 

24794 

24795 

24796 

24797 

24798 

24799 

24800 

24801 

24802 

24803 

24804 

24805 

24806 

24807 


• The fourth argument is a pointer to an FTW structure. The value of base is the offset of the 
object's file name in the path name passed as the first argument to fn . The value of level 
indicates depth relative to the root of the walk, where the root level is 0. 

The argument depth sets the maximum number of file descriptors that are shall be by nftiu () 
while traversing the file tree. At most one file descriptor shall be used for each directory level. 

RETURN VALUE 

The nftiu () function shall continue until the first of the following conditions occurs: 

• An invocation of fn shall return a non-zero value, in which case nftw () shall return that value. 

• The nftw() function detects an error other than [EACCES] (see FTW_DNR and FTW_NS 
above), in which case nftiu () shall return -1 and set errno to indicate the error. 

• The tree is exhausted, in which case nftiu () shall return 0. 

ERRORS 

The nftw () function shall fail if: 

[EACCES] Search permission is denied for any component of path or read permission is 

denied for path, or fn returns -1 and does not reset errno. 

[ENAMETOOLONG] 

The length of the path string exceeds [PATH_MAX[, or a path name 
component is longer than [NAME_MAX[. 

[ENOENT] A component of path does not name an existing file or path is an empty string. 

[ENOTDIR] A component of path is not a directory. 

The nftiu () function may fail if: 

[ELOOP] Too many symbolic links were encountered in resolving path. 

[EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 

[ENAMETOOLONG] 

Path name resolution of a symbolic link produced an intermediate result 
whose length exceeds {PATH_MAX[. 

[ENFILE] Too many files are currently open in the system. 

In addition, errno may be set if the function pointed by fn causes errno to be set. 

EXAMPLES 

The following example walks the /tmp directory and its subdirectories, calling the nftiu () 
function for every directory entry, to a maximum of 5 levels deep. 

#include <ftw.h> 

int nftwfunc (const char *, const struct stat *, int, struct FTW *); 

int nftwfunc (const char *filename, const struct stat *statptr, 
int fileflags, struct FTW *pfwt) 

{ 

return 0; 

} 

char *startpath = "/tmp"; 
int depth = 5; 

int flags = FTW_CHDIR | FTW_DEPTH | FTW_MOUNT; 
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24809 

24810 

24811 

24812 

24813 

24814 

24815 

24816 

24817 

24818 

24819 

24820 

24821 

24822 

24823 

24824 

24825 


int ret; 

ret = nftw (startpath, nftwfunc, depth, flags); 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

lstat() r opendir(), readdir(), stat(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <ftw.h> 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 

In the DESCRIPTION, the definition of the depth argument is clarified. 

Issue 6 

The Open Group Base Resolution bwg97-003 is applied. 
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NAME 

nice — change the nice value of a process 

SYNOPSIS 

xsi tinclude <unistd.h> 

int nice(int incr ); 


DESCRIPTION 

The nice () function shall add the value of incr to the nice value of the calling process. A process' 
nice value is a non-negative number for which a more positive value results in less favorable 
scheduling. 

A maximum nice value of 2*{NZERO}-l and a minimum nice value of 0 are imposed by the 
system. Requests for values above or below these limits result in the nice value being set to the 
corresponding limit. Only a process with appropriate privileges can lower the nice value. 

ps i tps Calling the nice() function has no effect on the priority of processes or threads with policy 
SCHED_FIFO or SCHED_RR. The effect on processes or threads with other scheduling policies 
is implementation-dependent. 

The nice value set with nice () shall be applied to the process. If the process is multi-threaded, the 
nice value shall affect all system scope threads in the process. 

As -1 is a permissible return value in a successful situation, an application wishing to check for 
error situations should set errno to 0, then call nice (), and if it returns -1, check to see if errno is 
non-zero. 

RETURN VALUE 

Upon successful completion, nice() shall return the new nice value -jNZERO}. Otherwise, -1 
shall be returned, the process' nice value shall not be changed, and errno shall be set to indicate 
the error. 

ERRORS 

The nice () function shall fail if: 

[EPERM] The incr argument is negative and the calling process does not have 

appropriate privileges. 

EXAMPLES 

Changing the Nice Value 

The following example adds the value of the incr argument, -20, to the nice value of the calling 
process. 

#include <unistd.h> 

int incr = -20; 
int ret; 

ret = nice (incr); 

APPLICATION USAGE 

None. 
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24866 RATIONALE 

24867 None. 

24868 FUTURE DIRECTIONS 

24869 None. 

24870 SEE ALSO 

24871 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <limits.h>, <unistd.h> 

24872 CHANGE HISTORY 

24873 First released in Issue 1. 

24874 Derived from Issue 1 of the SVID. 


24875 Issue 4 

24876 The <unistd.h> header is added to the SYNOPSIS section. 


24877 A statement is added to the DESCRIPTION indicating that the nice value can only be lowered by 

24878 a process with appropriate privileges. 

24879 Issue 4, Version 2 

24880 The RETURN VALUE section is updated for X/OPEN UNIX conformance to define that the 

24881 process' nice value is not changed if an error is detected. 


24882 Issue 5 

24883 A statement is added to the description indicating the effects of this function on the different 

24884 scheduling policies and multi-threaded processes. 
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24885 NAME 

24886 nl_langinfo — language information 

24887 SYNOPSIS 

24888 xsi #include <langinfo.h> 

24889 char *nl_langinfo(nl_item item); 

24890 

24891 DESCRIPTION 

24892 The nl_langinfo () function shall return a pointer to a string containing information relevant to 

24893 the particular language or cultural area defined in the program's locale (see <langinfo.h>). The 

24894 manifest constant names and values of item are defined in <langinfo.h>. For example: 

24895 nl_langinfo (ABDAY_1) 

24896 would return a pointer to the string "Dom" if the identified language was Portuguese, and 

24897 " Sun " if the identified language was English. 

24898 Calls to setlocale( ) with a category corresponding to the category of item (see <langinfo.h>), or to 

24899 the category LC_ALL, may overwrite the array pointed to by the return value. 

24900 The nljanginfo () function need not be reentrant. A function that is not required to be reentrant is 

24901 not required to be thread-safe. 

24902 RETURN VALUE 

24903 In a locale where langinfo data is not defined, nljanginfo () shall return a pointer to the 

24904 corresponding string in the POSIX locale. In all locales, nljanginfo () shall return a pointer to an 

24905 empty string if item contains an invalid setting. 

24906 This pointer may point to static data that may be overwritten on the next call. 

24907 ERRORS 

24908 No errors are defined. 

24909 EXAMPLES 

24910 Getting Date and Time Formatting Information 

24911 The following example returns a pointer to a string containing date and time formatting 

24912 information, as defined in the LCJTIME category of the current locale. 

24913 #include <time.h> 

24914 #include <langinfo.h> 

24915 

24916 strftime (datestring, sizeof (datestring), nl_langinfo (D_T_FMT), tm); 

24917 

24918 APPLICATION USAGE 

24919 The array pointed to by the return value should not be modified by the program, but may be 

24920 modified by further calls to nljanginfo (). 

24921 RATIONALE 

24922 None. 

24923 FUTURE DIRECTIONS 

24924 None. 
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24925 SEE ALSO 

24926 setlocale(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, <langinfo.h>, 

24927 <nl_types.il>, the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, I 

24928 Locale I 

24929 CHANGE HISTORY 

24930 First released in Issue 2. 

24931 Issue 4 

24932 The <nl_types.h> header is removed from the SYNOPSIS section. 

24933 Issue 5 

24934 The last paragraph of the DESCRIPTION is moved from the APPLICATION USAGE section. 

24935 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 
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24936 NAME 

24937 nrand48 — generate uniformly distributed pseudo-random non-negative long integers 

24938 SYNOPSIS 

24939 xsi #include <stdlib.h> 

24940 long int nrand48 (unsigned short int xsubi[3]); 

24941 

24942 DESCRIPTION 

24943 Refer to drand48 (). 
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24944 NAME 

24945 ntohl — convert values between host and network byte order 

24946 SYNOPSIS 

24947 #include <arpa/inet. h> 

24948 uint32_t ntohl (uint32_t netlong) ; 

24949 DESCRIPTION 

24950 Refer to h ton / (). 
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24951 NAME 

24952 ntohs — convert values between host and network byte order 

24953 SYNOPSIS 

24954 #include <arpa/inet. h> 

24955 uintl6_t ntohs (uintl6_t net short) ; 

24956 DESCRIPTION 

24957 Refer to h ton / (). 
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24958 NAME 

24959 open — open a file 

24960 SYNOPSIS 

24961 oh #include <sys/stat.h> 

24962 #include <fcntl.h> 

24963 int open (const char *path, int of lag, ... ) ; 

24964 DESCRIPTION 

24965 The open () function establishes the connection between a file and a file descriptor. It creates an 

24966 open file description that refers to a file and a file descriptor that refers to that open file 

24967 description. The file descriptor is used by other I/O functions to refer to that file. The path 

24968 argument points to a path name naming the file. 

24969 The open() function shall return a file descriptor for the named file that is the lowest file 

24970 descriptor not currently open for that process. The open file description is new, and therefore the 

24971 file descriptor does not share it with any other process in the system. The FD_CLOEXEC file 

24972 descriptor flag associated with the new file descriptor shall be cleared. 

24973 The file offset used to mark the current position within the file shall be set to the beginning of the 

24974 file. 

24975 The file status flags and file access modes of the open file description shall be set according to 

24976 the value of oflag. 

24977 Values for oflag are constructed by a bitwise-inclusive OR of flags from the following list, 

24978 defined in <fcntl.h>. Applications shall specify exactly one of the first three values (file access I 

24979 modes) below in the value of oflag: 

24980 0_RD0NLY Open for reading only. 

24981 0_WR0NLY Open for writing only. 

24982 0_RDWR Open for reading and writing. The result is undefined if this flag is applied to 

24983 a FIFO. 


24984 Any combination of the following may be used: 

24985 0_APPEND If set, the file offset shall be set to the end of the file prior to each write. 


24986 

24987 

24988 

24989 

24990 

24991 

24992 

24993 

24994 

24995 

24996 

24997 


0_CREAT If the file exists, this flag has no effect except as noted under 0_EXCL below. 

Otherwise, the file is created; the user ID of the file shall be set to the effective 
user ID of the process; the group ID of the file shall be set to the group ID of 
the file's parent directory or to the effective group ID of the process; and the 
access permission bits (see <sys/stat.h>) of the file mode shall be set to the 
value of the third argument taken as type mode_t modified as follows: a 
bitwise AND is performed on the file-mode bits and the corresponding bits in 
the complement of the process' file mode creation mask. Thus, all bits in the 
file mode whose corresponding bit in the file mode creation mask is set are 
cleared. When bits other than the file permission bits are set, the effect is 
unspecified. The third argument does not affect whether the file is open for 
reading, writing, or for both. 


24998 sio 0_DSYNC Write I/O operations on the file descriptor complete as defined by 

24999 synchronized I/O data integrity completion 


25000 0_EXCL If 0_CREAT and 0_EXCL are set, open() shall fail if the file exists. The check 

25001 for the existence of the file and the creation of the file if it does not exist shall 

25002 be atomic with respect to other processes executing open () naming the same 
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25003 

25004 

25005 

25006 

25007 

25008 

25009 

25010 

25011 

25012 

25013 

25014 

25015 

25016 

25017 

25018 

25019 

25020 

25021 

25022 

25023 

25024 

25025 

25026 

25027 

25028 

25029 

25030 

25031 

25032 

25033 

25034 

25035 

25036 

25037 

25038 

25039 

25040 

25041 

25042 

25043 

25044 

25045 

25046 

25047 


file name in the same directory with 0_EXCL and 0_CREAT set. If 0_EXCL I 
and CLCREAT are set, and path names a symbolic link, open () shall fail and set I 
errno to [EEXIST], regardless of the contents of the symbolic link. If 0_EXCL is I 
set and CLCREAT is not set, the result is undefined. I 

CLNOCTTY If set and path identify a terminal device, open () shall not cause the terminal 
device to become the controlling terminal for the process. 

CLNONBLOCK When opening a FIFO with 0_RDONLY or O.WRONLY set: 

• If 0_NONBLOCK is set, an open () for reading shall only return without 
delay. An open() for writing shall only return an error if no process 
currently has the file open for reading. 

• If 0_NONBLOCK is clear, an open() for reading shall only block the 
calling thread until a thread opens the file for writing. An open() for 
writing shall only block the calling thread until a thread opens the file for 
reading. 

When opening a block special or character special file that supports non- 
blocking opens: 

• If CLNONBLOCK is set, the open () function shall return without blocking 
for the device to be ready or available. Subsequent behavior of the device 
is device-specific. 

• If 0_NONBLOCK is clear, the open() function shall block the calling 
thread until the device is ready or available before returning. 

Otherwise, the behavior of 0_NONBLOCK is unspecified. 

sio 0_RSYNC Read I/O operations on the file descriptor complete at the same level of 

integrity as specified by the 0_DSYNC and 0_SYNC flags. If both 0_DSYNC 
and 0_RSYNC are set in oflag, all I/O operations on the file descriptor 
complete as defined by synchronized I/O data integrity completion. If both 
0_SYNC and 0_RSYNC are set in flags, all I/O operations on the file 
descriptor complete as defined by synchronized I/O file integrity completion. 

sio 0_SYNC Write I/O operations on the file descriptor complete as defined by 

synchronized I/O file integrity completion. 

0_TRUNC If the file exists and is a regular file, and the file is successfully opened 

0_RDWR or 0_WRONLY, its length is truncated to 0, and the mode and 
owner are unchanged. It shall have no effect on FIFO special files or terminal 
device files. Its effect on other file types is implementation-dependent. The 
result of using 0_TRUNC with 0_RDONLY is undefined. 

If 0_CREAT is set and the file did not previously exist, upon successful completion, open () shall 
mark for update the st_atime, stjctime, and stjntime fields of the file and the stjctime and 
st_mtime fields of the parent directory. 

If 0_TRUNC is set and the file did previously exist, upon successful completion, open () shall 
mark for update the stjctime and stjntime fields of the file. 

sio If both the 0_SYNC and 0_DSYNC flags are set, the effect is as if only the 0_SYNC flag was set. 

xsr If path refers to a STREAMS file, oflag may be constructed from CLNONBLOCK OR'ed with I 

either 0_RDONLY, 0_WRONLY, or 0_RDWR. Other flag values are not applicable to 
STREAMS devices and have no effect on them. The value 0_NONBLOCK affects the operation 
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of STREAMS drivers and certain functions applied to file descriptors associated with STREAMS 
files. For STREAMS drivers, the implementation of 0_NONBLOCK is device-specific. 

If path names the master side of a pseudo-terminal device, then it is unspecified whether open () 
locks the slave side so that it cannot be opened. Portable applications shall call nnlockpt() before I 
opening the slave side. 

man The largest value that can be represented correctly in an object of type off_t shall be established 
as the offset maximum in the open file description. 

RETURN VALUE 

Upon successful completion, the function shall open the file and return a non-negative integer 
representing the lowest numbered unused file descriptor. Otherwise, -1 shall be returned and 
errno set to indicate the error. No files shall be created or modified if the function returns -1. 


ERRORS 

The open () function shall fail if: 


sio 

XSR 


MAN 


[EACCES] Search permission is denied on a component of the path prefix, or the file 

exists and the permissions specified by oflag are denied, or the file does not 
exist and write permission is denied for the parent directory of the file to be 
created, or 0_TRUNC is specified and write permission is denied. 


[EEXIST] 0_CREAT and 0_EXCL are set, and the named file exists. 

[EINTR] A signal was caught during open (). 

[EINVAL] The implementation does not support synchronized 1/O for this file. 

[EIO] The path argument names a STREAMS file and a hangup or error occurred I 

during the open (). 


[EISDIR] The named file is a directory and oflag includes 0_WRONLY or 0_RDWR. 

[ELOOP] A loop exists in symbolic links encountered during resolution of the path I 

argument. I 


[EMFILE] |OPEN_MAX} file descriptors are currently open in the calling process. 

[ENAMETOOLONG] 

The length of the path argument exceeds {PATH_MAX} or a path name 
component is longer than {NAME_MAX} while _POSIX_NO_TRUNC is in 
effect. 


[ENFILE] The maximum allowable number of files is currently open in the system. 

[ENOENT] 0_CREAT is not set and the named file does not exist; or CLCREAT is set and 

either the path prefix does not exist or the path argument points to an empty 
string. 

xsr [ENOSR] The path argument names a STREAMS-based file and the system is unable to I 

allocate a STREAM. 

[ENOSPC] The directory or file system that would contain the new file cannot be 

expanded, the file does not exist, and 0_CREAT is specified. 

[ENOTDIR] A component of the path prefix is not a directory. 

[ENXIO] CLNONBLOCK is set, the named file is a FIFO, O.WRONLY is set, and no 

process has the file open for reading. 
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25090 

[ENXIO] 

The named file is a character special or block special file, and the device 
associated with this special file does not exist. 

25091 MAN 

25092 

[EOVERFLOW] 

The named file is a regular file and the size of the file cannot be represented 
correctly in an object of type off_t. 

25093 

25094 

25095 

[EROFS] 

The named file resides on a read-only file system and either 0_WRONLY, 
0_RDWR, 0_CREAT (if file does not exist), or 0_TRUNC is set in the oflag 
argument. 

25096 

The open () function may fail if: 

25097 XSR 

25098 

|E AGAIN] 

The path argument names the slave side of a pseudo-terminal device that is 
locked. 

25099 MAN 

[EINVAL] 

The value of the oflag argument is not valid. 

25100 

25101 

[ELOOP] 

More than {SYMLOOP_MAX} symbolic links were encountered during 
resolution of the path argument. 

25102 MAN 

25103 

25104 

[ENAMETOOLONG] 

As a result of encountering a symbolic link in resolution of the path argument, 
the length of the substituted path name string exceeded {PATH_MAX|. 

25105 XSR 

25106 

[ENOMEM] 

The path argument names a STREAMS file and the system is unable to allocate 
resources. 

25107 MAN 

25108 

[ETXTBSY] 

The file is a pure procedure (shared text) file that is being executed and oflag is 
CLWRONLY or O.RDWR. 


25109 EXAMPLES 

25110 Opening a File for Writing by the Owner 

25111 The following example opens the file /tmp/file, either by creating it (if it does not already exist), 

25112 or by truncating its length to 0 (if it does exist). In the former case, if the call creates a new file, 

25113 the access permission bits in the file mode of the file are set to permit reading and writing by the 

25114 owner, and to permit reading only by group members and others. 

25115 If the call to open () is successful, the file is opened for writing. 

25116 #include <fcntl.h> 

25117 

25118 int fd; 


25119 

25120 

25121 

mode. 

char 

_t mode = S_IRUSR | S_IWUSR 
*filename = "/tmp/file"; 

| S_IRGRP 

| S_IROTH; 

25122 

25123 

f d = 

open (filename, 0_WRONLY | 

0_CREAT | 

0_TRUNC, mode); 
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25124 Opening a File Using an Existence Check 

25125 The following example uses the open () function to try to create the LOCKFILE file and open it 

25126 for writing. Because the open () function specifies the 0_EXCL flag, the call fails if the file already 

25127 exists. In that case, the program assumes that someone else is updating the password file and 

25128 exits. 

25129 #include <fcntl.h> 

25130 #include <stdio.h> 

25131 #include <stdlib.h> 

25132 #define LOCKFILE "/etc/ptmp" 

25133 

25134 int pfd; /* Integer for file descriptor returned by open () call. */ 

25135 

25136 if ( (pfd = open (LOCKFILE, 0_WR0NLY | 0_CREAT | 0_EXCL, 

25137 S_IRUSR | S_IWUSR | S_IRGRP | S_IROTH) ) == -1) 

25138 { 

25139 fprintf (stderr, "Cannot open /etc/ptmp. Try again later.\n"); 

25140 exit (1); 

25141 } 

25142 

25143 Opening a File for Writing 

25144 The following example opens a file for writing, creating the file if it does not already exist. If the 

25145 file does exist, the system truncates the file to zero bytes. 

25146 #include <fcntl.h> 

25147 #include <stdio.h> 

25148 #include <stdlib.h> 

25149 #define LOCKFILE "/etc/ptmp" 

25150 

25151 int pfd; 

25152 char filename [PATH_MAX+1 ] ; 

25153 

25154 if ((pfd = open (filename, 0_WR0NLY | 0_CREAT | 0_TRUNC, 

25155 S_IRUSR I S_IWUSR I S_IRGRP | S_IROTH) ) == -1) 

25156 { 

25157 perror ("Cannot open output file\n"); exit (1); 

25158 } 

25159 

25160 APPLICATION USAGE 

25161 None. 

25162 RATIONALE 

25163 Except as specified in this volume of IEEE Std. 1003.1-200x, the flags allowed in oflag are not 

25164 mutually-exclusive and any number of them may be used simultaneously. 

25165 Some implementations permit opening FIFOs with 0_RDWR. Since FIFOs could be 

25166 implemented in other ways, and since two file descriptors can be used to the same effect, this 

25167 possibility is left as undefined. 

25168 See getgronps () about the group of a newly created file. 
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25169 The use of open() to create a regular file is preferable to the use of creat( ), because the latter is 

25170 redundant and included only for historical reasons. 

25171 The use of the 0_TRUNC flag on FIFOs and directories (pipes cannot be open ()-ed) must be 

25172 permissible without unexpected side effects (for example, creat() on a FIFO must not remove 

25173 data). Because terminal special files might have type-ahead data stored in the buffer, 0_TRUNC 

25174 should not affect their content, particularly if a program that normally opens a regular file 

25175 should open the current controlling terminal instead. Other file types, particularly 

25176 implementation-dependent ones, are left implementation-dependent. 

25177 Implementations may deny access and return [EACCES] for reasons other than just those listed I 

25178 in the [EACCES] definition. I 

25179 The 0_N0CTTY flag was added to allow applications to avoid unintentionally acquiring a 

25180 controlling terminal as a side effect of opening a terminal file. This volume of 

25181 IEEE Std. 1003.1-200x does not specify how a controlling terminal is acquired, but it allows an 

25182 implementation to provide this on open () if the 0_N0CTTY flag is not set and other conditions 

25183 specified in the System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, I 

25184 General Terminal Interface are met. The 0_N0CTTY flag is an effective no-op if the file being I 

25185 opened is not a terminal device. 

25186 In historical implementations the value of 0_RD0NLY is zero. Because of that, it is not possible 

25187 to detect the presence of 0_RD0NLY and another option. Future implementations should 

25188 encode 0_RD0NLY and 0_WR0NLY as bit flags so that: 

25189 0_RD0NLY | 0_WR0NLY == 0_RDWR 

25190 In general, the open () function follows the symbolic link if path names a symbolic link. However, I 

25191 the open () function, when called with 0_CREAT and 0_EXCL, is required to fail with [EEXIST] I 

25192 if path names an existing symbolic link, even if the symbolic link refers to a nonexistent file. This I 

25193 behavior is required so that privileged applications can create a new file in a known location I 

25194 without the possibility that a symbolic link might cause the file to be created in a different I 

25195 location. I 

25196 For example, a privileged application that must create a file with a predictable name in a user- I 

25197 writable directory, such as the user's home directory, could be compromised if the user creates a I 

25198 symbolic link with that name that refers to a nonexistent file in a system directory. If the user can I 

25199 influence the contents of a file, the user could compromise the system by creating a new system I 

25200 configuration or spool file that would then be interpreted by the system. The test for a symbolic I 

25201 link which refers to a nonexisting file must be atomic with the creation of a new file. I 

25202 FUTURE DIRECTIONS 

25203 None. 

25204 SEE ALSO 

25205 chmod(), close(), creat(), dnp(), fcntl(), lseek(), read(), umask( ), nnlockpt(), ivrite(), the System 

25206 Interface Definitions volume of IEEE Std. 1003.1-200x, <fcntl.h>, <sys/stat.h>, <sys/types.h> 

25207 CHANGE HISTORY 

25208 First released in Issue 1. 

25209 Derived from Issue 1 of the SVID. 


25210 Issue 4 

25211 The <sys/types.h> and <sys/stat.h> headers are now marked as optional (OH); these headers do 

25212 not need to be included on XSI-conformant systems. 


25213 0_NDELAY is removed from the list of oflag values (this flag was marked WITHDRAWN in 

25214 Issue 3). 
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25215 

25216 

25217 

25218 

25219 

25220 

25221 

25222 

25223 

25224 

25225 

25226 

25227 

25228 

25229 

25230 

25231 

25232 

25233 

25234 

25235 

25236 

25237 

25238 

25239 

25240 

25241 

25242 

25243 

25244 

25245 

25246 

25247 

25248 

25249 

25250 

25251 

25252 

25253 

25254 

25255 


The [ENXIO] error (for the condition where the file is a character or block special file and the 

associated device does not exist) and the [EINVAL] error are marked as extensions. 

The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

• The type of argument path is changed from char* to const char*. 

• Various wording changes are made to the DESCRIPTION to improve clarity and to align the 
text with the ISO POSIX-1 standard. 

The following changes are incorporated for alignment with the FIPS requirements: 

• In the DESCRIPTION, the description of 0_CREAT is amended and the relevant part marked 
as an extension. 

• In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 
name component is larger that |NAME_MAX} is now defined as mandatory and marked as 
an extension. 

Issue 4, Version 2 

The following changes are incorporated for X/OPEN UNIX conformance: 

• The DESCRIPTION is updated to define the use of open flags with STREAMS files, and to 
identify special considerations when opening the master side of a pseudo-terminal. 

• In the ERRORS section, the [EIO], [ELOOP], and [ENOSR] mandatory error conditions are 
added, and the [EAGAIN], [ENAMETOOLONG], and [ENOMEM] optional error conditions 
are added. 

Issue 5 

The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 

Threads Extension. 

Large File Summit extensions are added. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 
This is since behavior may vary from one file system to another. 

The following new requirements on POSIX implementations derive from alignment with the 

Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• In the DESCRIPTION, 0_CREAT is amended to state that the group ID of the file is set to the 
group ID of the file's parent directory or to the effective group ID of the process. This is a 
FIPS requirement. 

• In the DESCRIPTION, text is added to indicate setting of the offset maximum in the open file 
description. This change is to support large files. 

• In the ERRORS section, the [EOVERFLOW] condition is added. This change is to support 
large files. 

• The [ENXIO] mandatory error condition is added. 
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25259 

25260 

25261 

25262 

25263 


• The [EINVAL], [ENAMETOOLONG], and [ETXTBSY] optional error conditions are added. 

The DESCRIPTION and ERRORS sections are updated so that items related to the optional XSI 
STREAMS Option Group are marked. 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• An explanation is added of the effect of the 0_CREAT and 0_EXCL flags when the path 
refers to a symbolic link. 

• The [ELOOP] optional error condition is added. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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25264 NAME 

25265 opendir — open a directory 

25266 SYNOPSIS 

25267 #include <dirent.h> 


25268 DIR *opendir(const char * dirname)-, 

25269 DESCRIPTION 

25270 The opendir () function shall open a directory stream corresponding to the directory named by 

25271 the dirname argument. The directory stream is positioned at the first entry. If the type DIR is 

25272 implemented using a file descriptor, applications shall only be able to open up to a total of 

25273 ]OPEN_MAX[ files and directories. 


25274 RETURN VALUE 

25275 Upon successful completion, opendir () shall return a pointer to an object of type DIR. 

25276 Otherwise, a null pointer shall be returned and errno set to indicate the error. 


25277 ERRORS 

25278 The opendir () function shall fail if: 


25279 

25280 


[EACCES] 


Search permission is denied for the component of the path prefix of dirname or 
read permission is denied for dirname. 


25281 MAN [ELOOP] 

25282 


A loop exists in symbolic links encountered during resolution of the dirname I 
argument. I 


25283 

25284 

25285 

25286 


[ENAMETOOLONG] 

The length of the dirname argument exceeds |PATH_MAX}, or a path name 
component is longer than {NAME_MAX} while _POSIX_NO_TRUNC is in 
effect. 


25287 

25288 


[ENOENT] A component of dirname does not name an existing directory or dirname is an 

empty string. 


25289 


[ENOTDIR] A component of dirname is not a directory. 


25290 


The opendir () function may fail if: 


25291 

25292 


[ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during I 

resolution of the dirname argument. I 


25293 

25294 MAN 

25295 

25296 

25297 


[EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 

[ENAMETOOLONG] 

As a result of encountering a symbolic link in resolution of the dirname I 
argument, the length of the substituted path name string exceeded I 
|PATH_MAX[. I 


25298 


[ENFILE] Too many files are currently open in the system. 
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25299 EXAMPLES 

25300 Open a Directory Stream 

25301 The following program fragment demonstrates how the opendir () function is used. 


25302 

#include <sys/types.h> 


25303 

#include <dirent.h> 


25304 

#include <libgen.h> 


25305 



25306 

DIR *dir; 


25307 

struct dirent *dp; 


25308 



25309 

if ((dir = opendir (".")) == 

NULL) { 

25310 

perror ("Cannot open .") 

r 

25311 

exit (1); 


25312 

} 


25313 

while ((dp = readdir (dir)) 

!= NULL) 


25314 

25315 APPLICATION USAGE 

25316 The opendir( ) function should be used in conjunction with readdir (), closedir( ), and reiuinddir( ) to 

25317 examine the contents of the directory (see the EXAMPLES section in readdir( )). This method is 

25318 recommended for portability. 

25319 RATIONALE 

25320 Based on historical implementations, the rules about file descriptors apply to directory streams 

25321 as well. However, this volume of IEEE Std. 1003.1-200x does not mandate that the directory 

25322 stream be implemented using file descriptors. The description of opendir() clarifies that if a file 

25323 descriptor is used for the directory stream, it is mandatory that closedir() deallocate the file 

25324 descriptor. When a file descriptor is used to implement the directory stream, it behaves as if the 

25325 FD_CLOEXEC had been set for the file descriptor. 

25326 The returned value of readdir() merely represents a directory entry. No equivalence should be 

25327 inferred. 

25328 The directory entries for dot and dot-dot are optional. This volume of IEEE Std. 1003.1-200x does 

25329 not provide a way to test a priori for their existence because an application that is portable must 

25330 be written to look for (and usually ignore) those entries. Writing code that presumes that they 

25331 are the first two entries does not always work, as many implementations permit them to be 

25332 other than the first two entries, with a "normal” entry preceding them. There is negligible value 

25333 in providing a way to determine what the implementation does because the code to deal with 

25334 dot and dot-dot must be written in any case and because such a flag would add to the list of 

25335 those flags (which has proven in itself to be objectionable) and might be abused. 

25336 Since the structure and buffer allocation, if any, for directory operations are defined by the 

25337 implementation, this volume of IEEE Std. 1003.1-200x imposes no portability requirements for 

25338 erroneous program constructs, erroneous data, or the use of indeterminate values such as the 

25339 use or referencing of a dirp value or a dirent structure value after a directory stream has been 

25340 closed or after a fork( ) or one of the exec function calls. 

25341 Historical implementations of readdir() obtain multiple directory entries on a single read 

25342 operation, which permits subsequent readdir() operations to operate from the buffered 

25343 information. Any wording that required each successful readdir() operation to mark the 

25344 directory st_atinie field for update would militate against the historical performance-oriented 

25345 implementations. 
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25346 Since readdir() returns NULL when it detects an error and when the end of the directory is 

25347 encountered, an application that needs to tell the difference must set errno to zero before the call 

25348 and check it if NULL is returned. Because the function must not change errno in the second case I 

25349 and must set it to a non-zero value in the first case, a zero errno after a call returning NULL I 

25350 indicates end of directory; otherwise, an error. 

25351 Routines to deal with this problem more directly were proposed: 

25352 int derror ( dirp ) 

25353 DIR *dirp; 

25354 void clearderr (dirp) 

25355 DIR * dirp; 

25356 The first would indicate whether an error had occurred, and the second would clear the error 

25357 indication. The simpler method involving errno was adopted instead by requiring that readdir() 

25358 not change errno when end-of-directory is encountered. 

25359 An error or signal indicating that a directory has changed while open was considered but 

25360 rejected. 

25361 The thread-safe version of the directory reading function shall return values in a user-supplied 

25362 buffer instead of possibly using a static data area that may be overwritten by each call. Either the 

25363 |NAME_MAX} compile-time constant or the corresponding pathconf() option can be used to I 

25364 determine the maximum sizes of returned path names. 

25365 FUTURE DIRECTIONS 

25366 None. 

25367 SEE ALSO 

25368 closedir(), lstat(), readdir(), rewinddir (), symtink( ), the System Interface Definitions volume of 

25369 IEEE Std. 1003.1-200x, <dirent.h>, <limits.h>, <sys/types.h> 

25370 CHANGE HISTORY 

25371 First released in Issue 2. 

25372 Issue 4 

25373 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

25374 XSI-conformant systems. 

25375 In the DESCRIPTION, the following sentence is moved to the System Interface Definitions 

25376 volume of IEEE Std. 1003.1-200x: "The type DIR, which is defined in <dirent.h>, represents a 

25377 directory stream, which is an ordered sequence of all directory entries in a particular directory." 

25378 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

25379 • The type of argument dirname is changed from char* to const char*. 

25380 • The generation of an [ENOENT] error when dirname points to an empty string is made 

25381 mandatory. 

25382 The following change is incorporated for alignment with the FIPS requirements: 

25383 • In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 

25384 name component is larger that |NAME_MAX} is now defined as mandatory and marked as I 

25385 an extension. 
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25386 

25387 

25388 

25389 

25390 

25391 

25392 

25393 

25394 

25395 

25396 

25397 

25398 

25399 

25400 

25401 

25402 

25403 

25404 

25405 


Issue 4, Version 2 

The ERRORS section is updated for X/OPEN UNIX conformance as follows: 

• It states that [ELOOP] is returned if too many symbolic links are encountered during path 
name resolution. 

• A second [ENAMETOOLONG] condition is defined that may report excessive length of an 
intermediate result of path name resolution of a symbolic link. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 
This is since behavior may vary from one file system to another. 

The following new requirements on POSIX implementations derive from alignment with the 

Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• The [ELOOP] mandatory error condition is added. 

• A second [ENAMETOOLONG] is added as an optional error condition. 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• The [ELOOP] optional error condition is added. 
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25406 NAME 

25407 openlog — open a connection to the logging facility 

25408 SYNOPSIS 

25409 xsi tinclude <syslog.h> 

25410 void openlog (const char *ident, int logopt, int facility) ; 

25411 

25412 DESCRIPTION 

25413 Refer to closelog{). 
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25414 NAME 

25415 optarg, opterr, optind, optopt — options parsing variables 

25416 SYNOPSIS 

25417 #include <unistd.h> 

25418 extern char *optarg; 

25419 extern int opterr, optind, optopt; 

25420 DESCRIPTION 

25421 Refer to getopt (). 
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25422 NAME 

25423 pathconf — get configurable path name variables 

25424 SYNOPSIS 

25425 tinclude <unistd.h> 

25426 long int pathconf (const char *path r int name ) ; 

25427 DESCRIPTION 

25428 Refer to fpathconf(). 


812 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


pauseO 


25429 

25430 

25431 

25432 

25433 

25434 

25435 

25436 

25437 

25438 

25439 

25440 

25441 

25442 

25443 

25444 

25445 

25446 

25447 

25448 

25449 

25450 

25451 

25452 

25453 

25454 

25455 

25456 

25457 

25458 

25459 

25460 

25461 

25462 

25463 

25464 

25465 

25466 

25467 

25468 

25469 


NAME 

pause — suspend the thread until a signal is received 

SYNOPSIS 

#include <unistd.h> 
int pause(void) ; 

DESCRIPTION 

The pause( ) function shall suspend the calling thread until delivery of a signal whose action is 
either to execute a signal-catching function or to terminate the process. 

If the action is to terminate the process, pause( ) shall not return. 

If the action is to execute a signal-catching function, pause( ) shall return after the signal-catching 
function returns. 

RETURN VALUE 

Since pause{ ) suspends thread execution indefinitely unless interrupted by a signal, there is no 
successful completion return value. A value of -1 shall be returned and errno set to indicate the 
error. 

ERRORS 

The pause( ) function shall fail if: 

[EINTR] A signal is caught by the calling process and control is returned from the 

signal-catching function. 

EXAMPLES 

None. 

APPLICATION USAGE 

Many common uses of pause{) have timing windows. The scenario involves checking a 
condition related to a signal and, if the signal has not occurred, calling panse{ ). When the signal 
occurs between the check and the call to pause(), the process often blocks indefinitely. The 
sigprocmask () and s igsuspend() functions can be used to avoid this type of problem. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

sigsuspend( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The <unistd.h> header is added to the SYNOPSIS section. 

In the RETURN VALUE section, the text is expanded to indicate that process execution is 
suspended indefinitely "unless interrupted by a signal". 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The argument list is explicitly defined as void. 
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25470 Issue 5 

25471 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 

25472 Issue 6 

25473 The APPLICATION USAGE section is added. 
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25474 NAME 

25475 pclose — close a pipe stream to or from a process 

25476 SYNOPSIS 

25477 #include <stdio.h> 

25478 int pclose (FILE * stream) ; 

25479 DESCRIPTION 

25480 The pclose () function shall close a stream that was opened by popen(), wait for the command to 

25481 terminate, and return the termination status of the process that was running the command 

25482 language interpreter. However, if a call caused the termination status to be unavailable to 

25483 pclose (), then pclose ( ) shall return -1 with errno set to [ECHILD] to report this situation. This can 

25484 happen if the application calls one of the following functions: 

25485 • WClit{) 

25486 • luaitpid ( ) with a pid argument less than or equal to 0 or equal to the process ID of the 

25487 command line interpreter 

25488 • Any other function not defined in this volume of IEEE Std. 1003.1-200x that could do one of 

25489 the above 

25490 In any case, pclose () shall not return before the child process created by popen () has terminated. 

25491 If the command language interpreter cannot be executed, the child termination status returned 

25492 by pclose( ) is as if the command language interpreter terminated using exit(127) or _exit(127). 

25493 The pclose () function shall not affect the termination status of any child of the calling process 

25494 other than the one created by popen () for the associated stream. 

25495 If the argument stream to pclose () is not a pointer to a stream created by popen (), the result of 

25496 pclose () is undefined. 

25497 RETURN VALUE 

25498 Upon successful return, pclose () shall return the termination status of the command language 

25499 interpreter. Otherwise, pclose () shall return -1 and set errno to indicate the error. 

25500 ERRORS 

25501 The pclose () function shall fail if: 

25502 [ECHILD] The status of the child process could not be obtained, as described above. 

25503 EXAMPLES 

25504 None. 

25505 APPLICATION USAGE 

25506 None. 

25507 RATIONALE 

25508 There is a requirement that pclose () not return before the child process terminates. This is 

25509 intended to disallow implementations that return [EINTR] if a signal is received while waiting. 

25510 If pclose () returned before the child terminated, there would be no way for the application to 

25511 discover which child used to be associated with the stream, and it could not do the cleanup 

25512 itself. 

25513 If the stream pointed to by stream was not created by popen (), historical implementations of 

25514 pclose () return -1 without setting errno. To avoid requiring pclose () to set errno in this case, 

25515 IEEE Std. 1003.1-200x makes the behavior unspecified. An application should not use pclose( ) to 

25516 close any stream that was not created by popen (). 
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25517 

25518 

25519 

25520 

25521 

25522 

25523 

25524 

25525 

25526 

25527 

25528 

25529 

25530 

25531 

25532 

25533 

25534 

25535 

25536 

25537 

25538 

25539 

25540 

25541 

25542 

25543 

25544 

25545 

25546 

25547 

25548 

25549 

25550 

25551 

25552 

25553 

25554 

25555 

25556 

25557 

25558 

25559 

25560 

25561 

25562 


Some historical implementations of pclose( ) either block or ignore the signals SIGINT, SIGQUIT, 
and SIGHUP while waiting for the child process to terminate. Since this behavior is not 
described for the pclose() function in IEEEStd. 1003.l-200x, such implementations are not 
conforming. Also, some historical implementations return [EINTR] if a signal is received, even 
though the child process has not terminated. Such implementations are also considered non- 
conforming. 

Consider, for example, an application that uses: 

popen("command", " r ") 

to start command, which is part of the same application. The parent writes a prompt to its 
standard output (presumably the terminal) and then reads from the pop ()ed 
stream. The child reads the response from the user, does some transformation on the response 
(path name expansion, perhaps) and writes the result to its standard output. The parent process 
reads the result from the pipe, does something with it, and prints another prompt. The cycle 
repeats. Assuming that both processes do appropriate buffer flushing, this would be expected to 
work. To conform to IEEE Std. 1003.1-200x, pclose( ) must use ivaitpid (), or some similar function, 
instead of ivait (). 

The code sample below illustrates how the pclose( ) function might be implemented on a system 
conforming to IEEE Std. 1003.1-200x. 

int pclose(FILE ‘stream) 

{ 

int stat; 
pid_t pid; 

pid = <pid for process created for stream by popen()> 

(void) fclose(stream); 

while (waitpid(pid, &stat, 0) == -1) { 

if (errno != EINTR){ 
stat = -1; 
break; 

} 

} 

return(stat) ; 

} 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

fork(), popen (), ivaitpid (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

<stdio.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The following changes are incorporated for alignment with the ISO POSIX-2 standard: 

• The function is no longer marked as an extension. 

• The simple DESCRIPTION given in Issue 3 is replaced with a more complete description in 
this issue. In particular, interactions between this function and ivait () and ivaitpid () are 
defined. 
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25564 

25565 
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25570 

25571 

25572 

25573 

25574 

25575 

25576 

25577 

25578 

25579 
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25585 

25586 

25587 

25588 

25589 
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25591 
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25593 

25594 

25595 

25596 

25597 

25598 

25599 

25600 

25601 

25602 


NAME 

perror — write error messages to standard error 

SYNOPSIS 

#include <stdio.h> 

void perror(const char *s) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The perror( ) function maps the error number accessed through the symbol errno to a language- 
dependent error message, which shall be written to the standard error stream as follows: 

• First (if s is not a null pointer and the character pointed to by s is not the null byte), the string 
pointed to by s followed by a colon and a <space> character. 

• Then an error message string followed by a <newline> character. 

The contents of the error message strings are the same as those returned by strerror{) with 
argument errno. 

cx The perror( ) function shall mark the file associated with the standard error stream as having 

been written ( stjctime , stjntime marked for update) at some time between its successful 
completion and exit( ), abort (), or the completion of /flush () or fclose( ) on stderr. 

The perror( ) function shall not change the orientation of the standard error stream. 

RETURN VALUE 

The perror( ) function shall return no value. 

ERRORS 

No errors are defined. 

EXAMPLES 

Printing an Error Message for a Function 

The following example replaces bufptr with a buffer that is the necessary size. If an error occurs, 
the perror () function prints a message and the program exits. 

#include <stdio.h> 

#include <stdlib.h> 

char *bufptr; 
size_t szbuf; 

if ((bufptr = malloc (szbuf)) == NULL) { 
perror ("malloc"); exit (2); 

} 

APPLICATION USAGE 

None. 
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25603 RATIONALE 

25604 None. 

25605 FUTURE DIRECTIONS 

25606 None. 

25607 SEE ALSO 

25608 strerror( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdio.h> 

25609 CHANGE HISTORY 

25610 First released in Issue 1. 

25611 Derived from Issue 1 of the SVID. 

25612 Issue 4 

25613 The language for error message strings was given as implementation-dependent in Issue 3. In 

25614 this issue, they are defined as language-dependent. 

25615 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

25616 • A paragraph is added to the DESCRIPTION defining the effects of this function on the 

25617 stjctime and s t_mtime fields of the standard error stream. 

25618 The following change is incorporated for alignment with the ISO C standard: 

25619 • The type of argument s is changed from char* to const char*. 

25620 Issue 5 

25621 A paragraph is added to the DESCRIPTION indicating that perror() does not change the 

25622 orientation of the standard error stream. 

25623 Issue 6 

25624 Extensions beyond the ISO C standard are now marked. 
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25625 NAME 

25626 pipe — create an interprocess channel 

25627 SYNOPSIS 

25628 #include <unistd.h> 

25629 int pipe (int fildes[ 2]); 

25630 DESCRIPTION 

25631 The pipe() function shall create a pipe and place two file descriptors, one each into the 

25632 arguments fildes [0] and fildes [1], that refer to the open file descriptions for the read and write 

25633 ends of the pipe. Their integer values shall be the two lowest available at the time of the pipe( ) 

25634 call. The 0_N0NBL0CK and FD_CLOEXEC flags shall be clear on both file descriptors. (The 

25635 fcntl () function can be used to set both these flags.) 

25636 Data can be written to the file descriptor fildes[l] and read from the file descriptor fildes [0], A 

25637 read on the file descriptor fildes [0] shall access data written to the file descriptor fildes[l] on a 

25638 man first-in-first-out basis. It is unspecified whether fildes [0] is also open for writing and whether 

25639 fildes [1] is also open for reading. 

25640 A process has the pipe open for reading (correspondingly writing) if it has a file descriptor open 

25641 that refers to the read end, fildes [0] (write end, fildes [1]). 

25642 Upon successful completion, pipe() shall mark for update the st_atime, st_ctime, and stjntime 

25643 fields of the pipe. 

25644 RETURN VALUE 

25645 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 

25646 indicate the error. 

25647 ERRORS 

25648 The pipe( ) function shall fail if: 

25649 [EMFILE] More than {OPEN_MAX} minus two file descriptors are already in use by this 

25650 process. 

25651 [ENFILE] The number of simultaneously open files in the system would exceed a 

25652 system-imposed limit. 

25653 EXAMPLES 

25654 None. 

25655 APPLICATION USAGE 

25656 None. 

25657 RATIONALE 

25658 The wording carefully avoids using the verb "to open" in order to avoid any implication of use 

25659 of open ( ); see also zvrite (). 

25660 FUTURE DIRECTIONS 

25661 None. 

25662 SEE ALSO 

25663 fcntl (), read(), write (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

25664 <fcntl.h>, <unistd.h> 

25665 CHANGE HISTORY 

25666 First released in Issue 1. 

25667 Derived from Issue 1 of the SVID. 
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25670 

25671 

25672 

25673 

25674 

25675 

25676 

25677 


Issue 4 

The <unistd.h> header is added to the SYNOPSIS section. 

Issue 4, Version 2 

The DESCRIPTION is updated for X/OPEN UNIX conformance to indicate that certain 
dispositions oifildes [0] and/z7des[l] are unspecified. 

Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The DESCRIPTION is updated to indicate that certain dispositions of fildes [0] and fildes[l] 
are unspecified. 
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25678 NAME 

25679 poll — input /output multiplexing 

25680 SYNOPSIS 

25681 xsi tinclude <poll.h> 

25682 int poll (struct pollfd fds [ ] , nfds_t nfds, int timeout) ; 

25683 


25684 DESCRIPTION 


25685 

25686 

25687 

25688 

25689 


The poll () function provides applications with a mechanism for multiplexing input/output over 
a set of file descriptors. For each member of the array pointed to by fds, poll () examines the given 
file descriptor for the event(s) specified in events. The number of pollfd structures in th e fds 
array is specified by nfds. The poll() function identifies those file descriptors on which an 
application can read or write data, or on which certain events have occurred. 


25690 

25691 

25692 

25693 

25694 

25695 XSR 

25696 

25697 XSR 

25698 

25699 XSR 

25700 

25701 XSR 

25702 

25703 

25704 

25705 

25706 


Th e fds argument specifies the file descriptors to be examined and the events of interest for each 
file descriptor. It is a pointer to an array with one member for each open file descriptor of 
interest. The array's members are pollfd structures within which fd specifies an open file 
descriptor and events and revents are bitmasks constructed by OR'ing a combination of the 
following event flags: 

POLLIN Data other than high-priority data may be read without blocking. For 

STREAMS, this flag is set in revents even if the message is of zero length. 

POLLRDNORM Normal data (priority band equals 0) may be read without blocking. For 
STREAMS, this flag is set in revents even if the message is of zero length. 

POLLRDBAND Data from a non-zero priority band may be read without blocking. For 
STREAMS, this flag is set in revents even if the message is of zero length. 

POLLPRI High-priority data may be received without blocking. For STREAMS, this flag 

is set in revents even if the message is of zero length. 

POLLOUT Normal data (priority band equals 0) may be written without blocking. 

POLLWRNORM Same as POLLOUT. 

POLLWRBAND Priority data (priority band >0) may be written. This event only examines 
bands that have been written to at least once. 


25707 

25708 


POLLERR An error has occurred on the device or stream. This flag is only valid in the 

revents bitmask; it is ignored in the events member. 


25709 

25710 

25711 

25712 

25713 


POLLHUP The device has been disconnected. This event and POLLOUT are mutually- 

exclusive; a stream can never be writable if a hangup has occurred. However, 
this event and POLLIN, POLLRDNORM, POLLRDBAND, or POLLPRI are not 
mutually-exclusive. This flag is only valid in the revents bitmask; it is ignored 
in the events member. 


25714 

25715 


POLLNVAL The specified fd value is invalid. This flag is only valid in the revents member; 
it is ignored in the events member. 


25716 If the value of fd is less than 0, events is ignored, and revents is set to 0 in that entry on return from 

25717 poll (). 


25718 In each pollfd structure, poll() clears the revents member, except that where the application 

25719 requested a report on a condition by setting one of the bits of events listed above, poll() sets the 

25720 corresponding bit in revents if the requested condition is true. In addition, poll() sets the 

25721 POLLHUP, POLLERR, and POLLNVAL flag in revents if the condition is true, even if the 
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25723 

25724 

25725 

25726 

25727 

25728 

25729 

25730 

25731 

25732 

25733 

25734 

25735 

25736 

25737 

25738 

25739 

25740 

25741 

25742 

25743 

25744 

25745 

25746 

25747 

25748 

25749 

25750 

25751 

25752 

25753 

25754 

25755 

25756 

25757 

25758 

25759 

25760 

25761 

25762 

25763 


application did not set the corresponding bit in events. 

If none of the defined events have occurred on any selected file descriptor, poll () waits at least 
timeout milliseconds for an event to occur on any of the selected file descriptors. If the value of 
timeout is 0, poll() shall return immediately. If the value of timeout is -1, poll() shall block until a 
requested event occurs or until the call is interrupted. 

Implementations may place limitations on the granularity of timeout intervals. If the requested 
timeout interval requires a finer granularity than the implementation supports, the actual 
timeout interval shall be rounded up to the next supported value. 

The poll () function is not affected by the 0_NONBLOCK flag. 

xsr The poll() function supports regular files, terminal and pseudo-terminal devices, STREAMS- I 
based files,FIFOs, and pipes. The behavior of poll () on elements of fds that refer to other types of I 
file is unspecified. 

Regular files always poll TRUE for reading and writing. I 

The poll ( ) function supports sockets. I 

A file descriptor for a socket that is listening for connections shall indicate that it is ready for I 
reading, once connections are available. A file descriptor for a socket that is connecting I 
asynchronously shall indicate that it is ready for writing, once a connection has been established. I 

RETURN VALUE 

Upon successful completion, poll() shall return a non-negative value. A positive value indicates 
the total number of file descriptors that have been selected (that is, file descriptors for which the 
revents member is non-zero). A value of 0 indicates that the call timed out and no file descriptors 
have been selected. Upon failure, poll () shall return -1 and set err no to indicate the error. 

ERRORS 

The poll() function shall fail if: 

[EAGAIN] The allocation of internal data structures failed but a subsequent request may 

succeed. 

[EINTR] A signal was caught during poll (). 

xsr [EINVAL] The nfds argument is greater than |OPEN_MAX}, or one of the fd members I 

refers to a STREAM or multiplexer that is linked (directly or indirectly) 
downstream from a multiplexer. I 

EXAMPLES 

Checking for Events on a Stream 

The following example opens a pair of STREAMS devices and then waits for either one to 
become writeable. This example proceeds as follows: 

1. Sets the timeout parameter to 500 milliseconds. 

2. Opens the STREAMS devices /dev/devO and /dev/devl, and then polls them, specifying 
POLLOUT and POLLWRBAND as the events of interest. 

The STREAMS device names /dev/devO and /dev/devl are only examples of how 
STREAMS devices can be named; STREAMS naming conventions may vary among 
systems conforming to the IEEE Std. 1003.1-200x. 

3. Uses the ret variable to determine whether an event has occurred on either of the two 
STREAMS. The poll() function is given 500 milliseconds to wait for an event to occur (if it 
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has not occurred prior to the poll () call). 

Checks the returned value of ret. If a positive value is returned, one of the following can 
be done: 

a. Priority data can be written to the open STREAM on priority bands greater than 0, 
because the POLL WRB AND event occurred on the open STREAM (fds [0] or/els [1]). 

b. Data can be written to the open STREAM on priority-band 0, because the POLLOUT 
event occurred on the open STREAM (fds [0] or fds [1]). 

If the returned value is not a positive value, permission to write data to the open STREAM 
(on any priority band) is denied. 

If the POLLHUP event occurs on the open STREAM (fds [0] or fds [1 ]), the device on the 
open STREAM has disconnected. 

#include <stropts.h> 

#include <poll.h> 

struct pollfd fds[2]; 
int timeout_msecs = 500; 
int ret; 
int i; 

/* Open STREAMS device. */ 
fds[0].fd = open ("/dev/devO", ...); 

fds[l].fd = open ("/dev/devl" , ...); 

fds[0].events = POLLOUT | POLLWRBAND; 
fds[1].events = POLLOUT | POLLWRBAND; 

ret = poll (fds, 2, timeout_msecs); 

if (ret > 0) { 

/* An event on one of the fds has occurred. */ 
for (i=0; i<2; i++) { 

if (fds[i].revents & POLLWRBAND) { 

/* Priority data may be written on device number i. */ 

} 

if (fds[i].revents & POLLOUT) { 

/* Data may be written on device number i. */ 

} 

if (fds[i].revents & POLLHUP) { 

/* A hangup has occurred on device number i. */ 


pollO 

4. 

5. 

6 . 


APPLICATION USAGE 

None. 
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25807 RATIONALE 

25808 None. 

25809 FUTURE DIRECTIONS 

25810 None. 

25811 SEE ALSO 

25812 getmsg (), putmsg (), read(), select (), write (), the System Interface Definitions volume of 

25813 IEEE Std. 1003.1-200x, <poll.h>, <stropts.h>. Section 2.6 on page 55 

25814 CHANGE HISTORY 

25815 First released in Issue 4, Version 2. 

25816 Issue 5 

25817 Moved from X/OPEN UNIX extension to BASE. 

25818 The description of POLLWRBAND is updated. 

25819 Issue 6 

25820 Text referring to sockets is added to the DESCRIPTION. 

25821 Text relating to the XSI STREAMS Option Group is marked. 
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25822 NAME 

25823 popen — initiate pipe streams to or from a process 

25824 SYNOPSIS 

25825 #include <stdio.h> 

25826 FILE *popen (const char * command, const char *mode) ; 

25827 DESCRIPTION 

25828 The popen () function shall execute the command specified by the string command. It creates a 

25829 pip e between the calling program and the executed command, and returns a pointer to a stream 

25830 that can be used to either read from or write to the pipe. 

25831 The environment of the executed command shall be as if a child process were created within the I 

25832 popen () call using the fork () function, and the child used execl{ ) to invoke a command line I 

25833 interpreter. I 

25834 If the implementation supports the Commands and Utilities volume of IEEE Std. 1003.1-200x, I 

25835 the environment of the executed command is as if a child process were created within the 

25836 popen () call using fork( ), and the child invoked the sh utility using the call: 

25837 execl (shell path, "sh", "-c", command, (char *)0); 

25838 where shell path is an unspecified path name for the sh utility. 

25839 The popen () function ensures that any streams from previous popen () calls that remain open in 

25840 the parent process are closed in the new child process. 

25841 The mode argument to popen () is a string that specifies I/O mode: 

25842 1. If mode is r, when the child process is started, its file descriptor STDOUT_FILENO shall be 

25843 the writable end of the pipe, and the file descriptor fileno(stream) in the calling process, 

25844 where stream is the stream pointer returned by popen (), shall be the readable end of the 

25845 pipe. 

25846 2. If mode is zv, when the child process is started its file descriptor STDIN_FILENO shall be 

25847 the readable end of the pipe, and the file descriptor fileno(stream) in the calling process, 

25848 where stream is the stream pointer returned by popen (), shall be the writable end of the 

25849 pipe. 

25850 3. If mode is any other value, the result is undefined. 

25851 After popen (), both the parent and the child process shall be capable of executing independently 

25852 before either terminates. 

25853 Pipe streams are byte-oriented. 

25854 RETURN VALUE 

25855 Upon successful completion, popen () shall return a pointer to an open stream that can be used to I 

25856 read or write to the pipe. Otherwise, it shall return a null pointer and may set errno to indicate 

25857 the error. 

25858 ERRORS 

25859 The popen () function may fail if: 

25860 man [EMFILE] {FOPEN_MAX} or {STREAM_MAX} streams are currently open in the calling 

25861 process. 

25862 [EINVAL] The mode argument is invalid. 

25863 The popen () function may also set errno values as described by fork () or pipe( ). 
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25906 


EXAMPLES 

None. 

APPLICATION USAGE 

Because open files are shared, a mode r command can be used as an input filter and a mode zv 
command as an output filter. 

Buffered reading before opening an input filter may leave the standard input of that filter 
mispositioned. Similar problems with an output filter may be prevented by careful buffer 
flushing; for example, with /flush (). 

A stream opened by popen () should be closed by pclose (). 

The behavior of popen() is specified for values of mode of r and zv. Other modes such as rb and 
zvb might be supported by specific implementations, but these would not be portable features. 
Note that historical implementations of popen () only check to see if the first character of mode is 
r. Thus, a mode of robert the robot would be treated as mode r, and a mode of anything else would be 
treated as mode zv. 

If the application calls zvaitpid () or zvaitid () with a pid argument greater than 0, and it still has a 
stream that was called with popen () open, it must ensure that pid does not refer to the process 
started by popen (). 

To determine whether or not the environment specified in the Commands and Utilities volume 
of IEEE Std. 1003.1-200x is present, use the function call: 

sysconf(_SC_2_VERSION) 

(See sysconf ()). 

RATIONALE 

The popen () function should not be used by programs that have set user (or group) ID privileges. 
Th e fork() and exec family of functions (except execlp() and execvp ()), should be used instead. 
This prevents any unforeseen manipulation of the environment of the user that could cause 
execution of commands not anticipated by the calling program. 

If the original and pop ()ed processes both intend to read or write or read and write a common 
file, and either will be using FILE-type C functions (fread(), fzvrite(), and so on), the rules for 
streams must be observed. 

Because open files are shared, a mode r command can be used as an input filter and a mode w 
command as an output filter. 

The behavior of popen () is specified for modes of r and w. Other modes such as rb and wb 
might be supported by specific implementations, but these would not be portable features. Note 
that historical implementations of popen () only check to see if the first character of mode is ' r'. 
Thus, a mode of robert the robot would be treated as mode r, and a mode of anything else 
would be treated as mode w. 

If the application calls zvaitpid () with a pid argument greater than zero, and it still has a 
popen ()ed stream open, it must ensure that pid does not refer to the process started by popen (). 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

pclose(), pipeQ, sysconf(), system(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <stdio.h>, the Commands and Utilities volume of IEEE Std. 1003.1-200x 
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CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The APPLICATION USAGE section is extended. Only notes about buffer flushing are retained 
from Issue 3. 

The following changes are incorporated for alignment with the ISO POSIX-2 standard: 

• The function is no longer marked as an extension. 

• The type of arguments command and mode are changed from char* to const char*. 

• The DESCRIPTION is completely rewritten for alignment with the ISO POSIX-2 standard, 
although it describes essentially the same functionality as Issue 3. 

• The sh utility defined in the Commands and Utilities volume of IEEE Std. 1003.1-200x is no 
longer required in all circumstances. 

• The ERRORS section is added. 

Issue 5 

A statement is added to the DESCRIPTION indicating that pipe streams are byte-oriented. 

Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The optional [EMFILE] error condition is added. 

The following changes were made to align with the IEEE P1003.1a draft standard: I 

• The DESCRIPTION is adjusted to reflect the behavior on systems that do not support the I 

POSIX Shell option. I 
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25930 NAME 

25931 posix_fadvise — file advisory information 

25932 SYNOPSIS 

25933 adv #include <fcntl.h> 

25934 int posix_fadvise (int fd, off_t offset, size_t len, int advice ) ; 

25935 

25936 DESCRIPTION 

25937 The posix_fadvise( ) function provides advice to the implementation on the expected behavior of 

25938 the application with respect to the data in the file associated with the open file descriptor, fd, 

25939 starting at offset and continuing for len bytes. The specified range need not currently exist in the 

25940 file. If len is zero, all data following offset is specified. The implementation may use this 

25941 information to optimize handling of the specified data. The posix_fadvise( ) function has no effect 

25942 on the semantics of other operations on the specified data, though it may affect the performance 

25943 of other operations. 

25944 The advice to be applied to the data is specified by the advice parameter and may be one of the 

25945 following values: 

25946 POSIX_F AD V_N ORM AL 

25947 Specifies that the application has no advice to give on its behavior with respect to the 

25948 specified data. It is the default characteristic if no advice is given for an open file. 

25949 POSIX_FADV_SEQUENTIAL 

25950 Specifies that the application expects to access the specified data sequentially from lower 

25951 offsets to higher offsets. 

25952 POSIX_FADV_RANDOM 

25953 Specifies that the application expects to access the specified data in a random order. 

25954 POSIX_FADV_WILLNEED 

25955 Specifies that the application expects to access the specified data in the near future. 

25956 POSIX_FADV_DONTNEED 

25957 Specifies that the application expects that it will not access the specified data in the near 

25958 future. 

25959 POSIX_F AD V_N OREU SE 

25960 Specifies that the application expects to access the specified data once and then not reuse it 

25961 thereafter. 

25962 These values shall be defined in <fcntl.h> if the Advisory Information option is supported. 

25963 RETURN VALUE 

25964 Upon successful completion, posix_fadvise( ) shall return zero; otherwise, an error number shall 

25965 be returned to indicate the error. 

25966 ERRORS 

25967 The posix_fadvise( ) function shall fail if: 

25968 [EBADF] The/d argument is not a valid file descriptor. 

25969 [EINVAL] The value in advice is invalid. 

25970 [ESPIPE] Th e/d argument is associated with a pipe or FIFO. 
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25971 EXAMPLES 

25972 None. 

25973 APPLICATION USAGE 

25974 The posix_fadvise( ) function is part of the _POSIX_ADVISORY_INFO option and need not be 

25975 provided on all implementations. 

25976 RATIONALE 

25977 None. 

25978 FUTURE DIRECTIONS 

25979 None. 

25980 SEE ALSO 

25981 posix_madvise( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <fcntl.h> 

25982 CHANGE HISTORY 

25983 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 

25984 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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25985 NAME 

25986 posix_fallocate — file space control 

25987 SYNOPSIS 

25988 adv #include <fcntl.h> 

25989 int posix_fallocate (int fd, off_t offset, size_t len) ; 

25990 

25991 DESCRIPTION 

25992 The posix_fallocate( ) function ensures that any required storage for regular file data starting at 

25993 offset and continuing for len bytes is allocated on the file system storage media. If posix_fallocate () 

25994 returns successfully, subsequent writes to the specified file data shall not fail due to the lack of 

25995 free space on the file system storage media. 

25996 If the offset+len is beyond the current file size, then posix_fallocate() shall adjust the file size to 

25997 offset+len. Otherwise, the file size shall not be changed. 

25998 It is implementation-dependent whether a previous posix_fadvise() call influences allocation 

25999 strategy. 

26000 Space allocated via posix_fallocate() shall be freed by a successful call to creat() or open() that 

26001 truncates the size of the file. Space allocated via posix_fallocate( ) may be freed by a successful call 

26002 to ftrnncate( ) that reduces the file size to a size smaller than offset+len. 

26003 RETURN VALUE 

26004 Upon successful completion, posix_fallocate( ) shall return zero; otherwise, an error number shall 

26005 be returned to indicate the error. 

26006 ERRORS 

26007 The posix_fallocate( ) function shall fail if: 

26008 [EBADF] The/d argument is not a valid file descriptor. 

26009 [EBADF] The/d argument references a file that was opened without write permission. 

26010 [EFBIG] The value of offset+len is greater than the maximum file size. 

26011 [EINTR] A signal was caught during execution. 

26012 [EINVAL] The len argument was zero or the offset argument was less than zero. 

26013 [EIO] An I/O error occurred while reading from or writing to a file system. 

26014 [ENODEV] Th e/d argument does not refer to a regular file. 

26015 [ENOSPC] There is insufficient free space remaining on the file system storage media. 

26016 [ESPIPE] Th e/d argument is associated with a pipe or FIFO. 

26017 EXAMPLES 

26018 None. 

26019 APPLICATION USAGE 

26020 The posixffallocate( ) function is part of the _POSIX_ADVISORY_INFO option and need not be 

26021 provided on all implementations. 

26022 RATIONALE 

26023 None. 
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26024 FUTURE DIRECTIONS 

26025 None. 

26026 SEE ALSO 

26027 creat(), ftnmcate(), open(), unlink(), the System Interface Definitions volume of 

26028 IEEE Std. 1003.1-200x, <fcntl.h> 

26029 CHANGE HISTORY 

26030 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 

26031 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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26032 NAME 

26033 posix_madvise — memory advisory information and alignment control 

26034 SYNOPSIS 

26035 adv #include <sys/mman.h> 

26036 int posix_madvise (void * addr, size_t len, int advice) ; 

26037 

26038 Notes to Reviewers 

26039 This section zvith side shading zvill not appear in the final copy. - Ed. 

26040 Here is the first 1003.Id inconsistency. 1003.Id, Section 2.7.3 clearly states that posix_madvise( ) is 

26041 to be declared in <fcntl.h>, and no mention in that section is made of <sys/mman.h>. Yet in 

26042 20.2.1.1, the Synopsis states that the function is declared in <sys/mman.h>. One of these will 

26043 have to be changed via interpretation or technical corrigenda ballot. I'd be willing to bet that 

26044 <sys/mman.h> was intended and <fcntl.h> was an oversight. 

26045 DESCRIPTION 

26046 mfishm The posix_madvise() function need only be supported if either the _POSIX_MAPPED_FILES or 

26047 the _POSIX_SHARED_MEMORY_OBJECTS options are supported. 

26048 The posix_madvise( ) function provides advice to the implementation on the expected behavior of 

26049 the application with respect to the data in the memory starting at address addr, and continuing 

26050 for len bytes. The implementation may use this information to optimize handling of the specified 

26051 data. The posix_madvise( ) function has no effect on the semantics of access to memory in the 

26052 specified range, though it may affect the performance of access. 

26053 The implementation may require that addr be a multiple of the page size, which is the value 

26054 returned by sysconf( ) when the name value _SC_PAGESIZE is used. 

26055 The advice to be applied to the memory range is specified by the advice parameter and may be 

26056 one of the following values: 

26057 POSIX_M AD V_N ORM AL 

26058 Specifies that the application has no advice to give on its behavior with respect to the 

26059 specified range. It is the default characteristic if no advice is given for a range of memory. 

26060 POSIX_MADV_SEQUENTIAL 

26061 Specifies that the application expects to access the specified range sequentially from lower 

26062 addresses to higher addresses. 

26063 POSIX_MADV_RANDOM 

26064 Specifies that the application expects to access the specified range in a random order. 

26065 POSIX_MADV_WILLNEED 

26066 Specifies that the application expects to access the specified range in the near future. 

26067 POSIX_MADV_DONTNEED 

26068 Specifies that the application expects that it will not access the specified range in the near 

26069 future. 

26070 These values shall be defined in <sys/mman.h> if the Advisory Information option is supported 

26071 and either the Memory Mapped Files option or the Shared Memory Objects option is supported. 
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26072 RETURN VALUE 

26073 Upon successful completion, posix_madvise{ ) shall return zero; otherwise, an error number shall 

26074 be returned to indicate the error. 

26075 ERRORS 

26076 The posix_madvise{ ) function shall fail if: 

26077 [EINVAL] The value in advice is invalid. 

26078 [ENOMEM] Addresses in the range starting at addr and continuing for len bytes are partly 

26079 or completely outside the range allowed for the address space of the calling 

26080 process. 

26081 The posix_madvise() function may fail if: 

26082 [EINVAL] The value of addr is not a multiple of the value returned by sysconf( ) when the 

26083 name value _SC_PAGESIZE is used. 

26084 [EINVAL] The value of len is zero. 

26085 EXAMPLES 

26086 None. 

26087 APPLICATION USAGE 

26088 The posix_madvise{) function is part of the _POSIX_ADVISORY_INFO option and need not be 

26089 provided on all implementations. 

26090 RATIONALE 

26091 None. 

26092 FUTURE DIRECTIONS 

26093 None. 

26094 SEE ALSO 

26095 mmap(), posix_fadvise( ), sysconf(), the System Interface Definitions volume of 

26096 IEEE Std. 1003.1-200x, <sys/mmap.h> 

26097 CHANGE HISTORY 

26098 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 

26099 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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26100 NAME 

26101 posix_mem_offset — find offset and length of a mapped typed memory block 

26102 SYNOPSIS 

26103 TYM #include <sys/mman.h> 

26104 int posix_mem_offset (const void *addr, size_t len, off_t *off, 

26105 size_t * contig_len , int * fildes) ; 

26106 

26107 DESCRIPTION 

26108 The posix_mem_offset () function returns in the variable pointed to by off a value that identifies 

26109 the offset (or location), within a memory object, of the memory block currently mapped at addr. 

26110 The function shall return in the variable pointed to by fildes, the descriptor used (via mmap{ )) to 

26111 establish the mapping which contains addr. If that descriptor was closed since the mapping was 

26112 established, the returned value of fildes shall be -1. The len argument specifies the length of the 

26113 block of the memory object the user wishes the offset for; upon return, the value pointed to by 

26114 contigjen shall equal either len, or the length of the largest contiguous block of the memory 

26115 object that is currently mapped to the calling process starting at addr, whichever is smaller. 

26116 If the memory object mapped at addr is a typed memory object, then if the off and contigjen 

26117 values obtained by calling posix_mem_offset () are used in a call to mmap () with a file descriptor 

26118 that refers to the same memory pool as fildes (either through the same port or through a different 

26119 port), and that was opened with neither the POSIX_TYPED_MEM_ ALLOC ATE nor the 

26120 POSIX_TYPED_MEM_ALLOCATE_CONTIG flag, the typed memory area that is mapped shall 

26121 be exactly the same area that was mapped at addr in the address space of the process that called 

26122 posix_mem_offset (). 

26123 If the memory object specified by fildes is not a typed memory object, then the behavior of this 

26124 function is implementation-dependent. 

26125 RETURN VALUE 

26126 Upon successful completion, the posixjnemjoffset () function shall return zero; otherwise, the 

26127 corresponding error status value shall be returned. 

26128 ERRORS 

26129 The posix_mem_offset( ) function shall fail if: 

26130 [EACCES] The process has not mapped a memory object supported by this function at 

26131 the given address addr. 

26132 This function does not return an error code of [EINTR], 

26133 EXAMPLES 

26134 None. 

26135 APPLICATION USAGE 

26136 None. 

26137 RATIONALE 

26138 None. 

26139 FUTURE DIRECTIONS 

26140 None. 

26141 SEE ALSO 

26142 mmap(), posixJyped_mem_open (), the System Interface Definitions volume of 

26143 IEEE Std. 1003.1-200x, <sys/mman.h> 
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26144 CHANGE HISTORY 

26145 First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. 
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26146 NAME 

26147 posix_memalign — aligned memory allocation 

26148 SYNOPSIS 

26149 adv #include <stdlib.h> 

26150 int posix_memalign (void **memptr, size_t alignment, size_t size); 

26151 

26152 DESCRIPTION 

26153 The posixjnemalign () function allocates size bytes aligned on a boundary specified by alignment, 

26154 and returns a pointer to the allocated memory in memptr. The value of alignment must be a 

26155 multiple of sizeof (void), that is also a power of two. Upon successful completion, the value 

26156 pointed to by memptr shall be a multiple of alignment. 

26157 cx The free() function shall deallocate memory which has previously been allocated by 

26158 posix_memalign(). 

26159 RETURN VALUE 

26160 Upon successful completion, posixjnemalign () shall return zero; otherwise, an error number 

26161 shall be returned to indicate the error. 

26162 ERRORS 

26163 The posix_memalign () function shall fail if: 

26164 [EINVAL] The value of the alignment parameter is not a power of two multiple of 

26165 sizeof { void*). 

26166 [ENOMEM] There is insufficient memory available with the requested alignment. 

26167 EXAMPLES 

26168 None. 

26169 APPLICATION USAGE 

26170 The posixjnemalign () function is part of the _POSIX_ADVISORY_INFO option and need not be 

26171 provided on all implementations. 

26172 RATIONALE 

26173 None. 

26174 FUTURE DIRECTIONS 

26175 None. 

26176 SEE ALSO 

26177 free( ), malloc(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

26178 CHANGE HISTORY 

26179 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 

26180 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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26181 NAME 

26182 posix_spawn, posix_spawnp — spawn a process (REALTIME) 

26183 SYNOPSIS 

26184 SPN #include <spawn.h> 


26185 

int posix_spawn(pid_t *pid, const char *path, 

26186 

const posix_spawn_file_actions_t * file_actions, 

26187 

const posix_spawnattr_t *attrp, char * const argv[] , 

26188 

char * const envp[]); 

26189 

int posix_spawnp(pid_t *pid, const char *file, 

26190 

const posix_spawn_file_actions_t * file_actions, 

26191 

const posix_spawnattr_t *attrp, char * const argv[] , 

26192 

char * const envp[]); 


26193 

26194 DESCRIPTION 

26195 The posix_spaivn () and posix_spawnp () functions shall create a new process (child process) from 

26196 the specified process image. The new process image is constructed from a regular executable file 

26197 called the new process image file. 

26198 When a C program is executed as the result of this call, it shall be entered as a C language 

26199 function call as follows: 

26200 int main (int argc, char *argv []); 

26201 where argc is the argument count and argv is an array of character pointers to the arguments 

26202 themselves. In addition, the following variable: 

26203 extern char ** environ; 

26204 is initialized as a pointer to an array of character pointers to the environment strings. 

26205 The argument argv is an array of character pointers to null-terminated strings. The last member 

26206 of this array shall be a null pointer (this null pointer is not counted in argc). These strings 

26207 constitute the argument list available to the new process image. The value in argv[ 0] should 

26208 point to a file name that is associated with the process image being started by the posix_spaivn () 

26209 or posix_spawnp () function. 

26210 The argument envp is an array of character pointers to null-terminated strings. These strings 

26211 constitute the environment for the new process image. The environment array is terminated by a 

26212 null pointer. 

26213 The number of bytes available for the child process' combined argument and environment lists 

26214 is {ARG_MAX}. The implementation shall specify in the system documentation (see the System 

26215 Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 2, Conformance) whether any list 

26216 overhead, such as length words, null terminators, pointers, or alignment bytes, is included in 

26217 this total. 

26218 The path argument to posix_spazvn () is a path name that identifies the new process image file to 

26219 execute. 

26220 The file parameter to posix_spawnp{) shall be used to construct a path name that identifies the 

26221 new process image file. If the file parameter contains a slash character, the file parameter shall be 

26222 used as the path name for the new process image file. Otherwise, the path prefix for this file shall 

26223 be obtained by a search of the directories passed as the environment variable PATH (see the 

26224 System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment 

26225 Variables). If this environment variable is not defined, the results of the search are 

26226 implementation-dependent. 


838 


Technical Standard (2000) (Draft February 29, 2000) 





System Interfaces 


posix_spawn() 


26227 

26228 

26229 

26230 

26231 

26232 

26233 

26234 

26235 

26236 

26237 

26238 

26239 

26240 

26241 

26242 

26243 

26244 

26245 

26246 

26247 

26248 

26249 

26250 

26251 

26252 

26253 

26254 

26255 

26256 

26257 

26258 

26259 

26260 
26261 
26262 

26263 

26264 

26265 

26266 

26267 

26268 

26269 

26270 

26271 

26272 


If file_actions is a null pointer, then file descriptors open in the calling process shall remain open 
in the child process, except for those whose close-on -exec flag FD_CLOEXEC is set (see fcntl ()). 
For those file descriptors that remain open, all attributes of the corresponding open file 
descriptions, including file locks (seefcntl( )), shall remain unchanged. 

If file_actions is not NULL, then the file descriptors open in the child process shall be those open 
in the calling process as modified by the spawn file actions object pointed to by file_actions and 
the FD_CLOEXEC flag of each remaining open file descriptor after the spawn file actions have 
been processed. The effective order of processing the spawn file actions shall be: 

1. The set of open file descriptors for the child process shall initially be the same set as is 
open for the calling process. All attributes of the corresponding open file descriptions, 
including file locks (seefcntl()), shall remain unchanged. 

2. The signal mask and the effective user and group IDs for the child process shall be 
changed as specified in the attributes object referenced by attrp. 

3. The file actions specified by the spawn file actions object shall be performed in the order in 
which they were added to the spawn file actions object. 

4. Any file descriptor which has its FD_CLOEXEC flag set (see fcntl ()) shall be closed. 

The posix_spawnattr_t spawn attributes object type is defined in <spawn.h>. It shall contain at 
least the attributes defined below. 

If the POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute of the object 
referenced by attrp, and the spaivn-pgronp attribute of the same object is non-zero, then the 
child's process group shall be as specified in the spaivn-pgronp attribute of the object referenced 
by attrp. 

As a special case, if the POSIX_SPAWN_SETPGROUP flag is set in the spawn-flags attribute of 
the object referenced by attrp, and the spaivn-pgronp attribute of the same object is set to 0, then 
the child shall be in a new process group with a process group ID equal to its process ID. 

If the POSIX_SPAWN_SETPGROUP flag is not set in the spawn-flags attribute of the object 
referenced by attrp, the new child process shall inherit the parent's process group. 

If _POSIX_PRIORITY_SCHEDULING is defined, and the POSIX_SPAWN_SETSCHEDPARAM 
flag is set in the spawn-flags attribute of the object referenced by attrp, but 
POSIX_SPAWN_SETSCHEDULER is not set, the new process image shall initially have the 
scheduling policy of the calling process with the scheduling parameters specified in the spawn- 
schedparam attribute of the object referenced by attrp. 

If _POSIX_PRIORITY_SCHEDULING is defined, and the POSIX_SPAWN_SETSCHEDULER 
flag is set in spawn-flags attribute of the object referenced by attrp (regardless of the setting of the 
POSIX_SPAWN_SETSCHEDPARAM flag), the new process image shall initially have the 
scheduling policy specified in the spawn-schedpolicy attribute of the object referenced by attrp and 
the scheduling parameters specified in the spawn-schedparam attribute of the same object. 

The POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute of the object referenced by attrp 
governs the effective user ID of the child process. If this flag is not set, the child process inherits 
the parent process' effective user ID. If this flag is set, the child process' effective user ID is reset 
to the parent's real user ID. In either case, if the set-user-ID mode bit of the new process image 
file is set, the effective user ID of the child process will become that file's owner ID before the 
new process image begins execution. 

The POSIX_SPAWN_RESETIDS flag in the spawn-flags attribute of the object referenced by attrp 
also governs the effective group ID of the child process. If this flag is not set, the child process 
inherits the parent process' effective group ID. If this flag is set, the child process' effective group 
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26273 ID is reset to the parent's real group ID. In either case, if the set-group-ID mode bit of the new 

26274 process image file is set, the effective group ID of the child process will become that file's group 

26275 ID before the new process image begins execution. 

26276 If the POSIX_SPAWN_SETSIGMASK flag is set in the spawn-flags attribute of the object 

26277 referenced by attrp, the child process shall initially have the signal mask specified in the spaivn- 

26278 sigmask attribute of the object referenced by attrp. 

26279 If the POSIX_SPAWN_SETSIGDEF flag is set in the spazvn-flags attribute of the object referenced 

26280 by attrp, the signals specified in the spawn-sigdefault attribute of the same object shall be set to 

26281 their default actions in the child process. Signals set to the default action in the parent process 

26282 shall be set to the default action in the child process. 

26283 Signals set to be caught by the calling process shall be set to the default action in the child 

26284 process. 

26285 Signals set to be ignored by the calling process image shall be set to be ignored by the child 

26286 process, unless otherwise specified by the POSIX_SPAWN_SETSIGDEF flag being set in the 

26287 spazvn-flags attribute of the object referenced by attrp and the signals being indicated in the 

26288 spawn-sigdefault attribute of the object referenced by attrp. 

26289 If the value of the attrp pointer is NULL, then the default values are used. 

26290 All process attributes, other than those influenced by the attributes set in the object referenced 

26291 by attrp as specified above or by the file descriptor manipulations specified in file_actions, shall 

26292 appear in the new process image as though fork( ) had been called to create a child process and 

26293 then a member of the exec family of functions had been called by the child process to execute the 

26294 new process image. 

26295 If the Threads option is supported, then it is implementation-dependent whether the fork 

26296 handlers are run when posix_spazvn () or posix_spazvnp () is called. 

26297 RETURN VALUE 

26298 Upon successful completion, posix_spazvn () and posix_spazvnp () shall return the process ID of the 

26299 child process to the parent process, in the variable pointed to by a non-NULL pid argument, and 

26300 shall return zero as the function return value. Otherwise, no child process shall be created, the 

26301 value stored into the variable pointed to by a non-NULL pid is unspecified, and an error number 

26302 shall be returned as the function return value to indicate the error. If the pid argument is a null 

26303 pointer, the process ID of the child is not returned to the caller. 

26304 ERRORS 

26305 The posix_spazvn () and posix_spazvnp () functions may fail if: 

26306 [EINVAL] The value specified by file_actions or attrp is invalid. 

26307 If this error occurs after the calling process successfully returns from the posix_spawn() or 

26308 posix_spazvnp () function, the child process may exit with exit status 127. 

26309 If posix_spazvn () or posix_spazvnp () fail for any of the reasons that would cause fork () or one of 

26310 the exec family of functions to fail, an error value shall be returned (or, if the error occurs after 

26311 the calling process successfully returns, the child process exits with exit status 127), as described 

26312 by fork () and exec respectively. 

26313 If POSIX_SPAWN_SETPGROUP is set in the spazvn-flags attribute of the object referenced by 

26314 attrp, and posix_spazvn() or posix_spawnp () fails while changing the child's process group, an 

26315 error value shall be returned (or, if the error occurs after the calling process successfully returns, 

26316 the child process exits with exit status 127) as described by setpgid(). 


840 


Technical Standard (2000) (Draft February 29, 2000) 




System Interfaces 


posix_spawn() 


26317 If _POSIX_PRIORITY_SCHEDULING is defined, and POSIX_SPAWN_SETSCHEDPARAM is I 

26318 set and POSIX_SPAWN_SETSCHEDULER is not set in the spazvn-flags attribute of the object I 

26319 referenced by attrp, then if posix_spazvn () or posix_spazvnp() fails for any of the reasons that I 

26320 would cause sched_setparam () to fail, an error value shall be returned (or, if the error occurs after I 

26321 the calling process successfully returns, the child process exits with exit status 127) as described I 

26322 by sched_setparam(). I 

26323 If _POSIX_PRIORITY_SCHEDULING is defined, and POSIX_SPAWN_SETSCHEDULER is set I 

26324 in the spazvn-flags attribute of the object referenced by attrp, then if posix_spazvn{) or I 

26325 posix_spazvnp{) fails for any of the reasons that would cause sched_setschednler( ) to fail, an error I 

26326 value shall be returned (or, if the error occurs after the calling process successfully returns, the I 

26327 child process exits with exit status 127) as described by sched_setschednler( ). I 

26328 If the file_actions argument is not NULL, and specifies any close, dnp2, or open actions to be I 

26329 performed, and posix_spazvn () or posix_spazvnp() fails for any of the reasons that would cause I 

26330 close (), dnp2 (), or open () to fail, an error value shall be returned (or, if the error occurs after the I 

26331 calling process successfully returns, the child process exits with exit status 127) as described by I 

26332 close (), dup2 (), and open(), respectively. An open file action may, by itself, result in any of the I 

26333 errors described by close () or dnp2 (), in addition to those described by open (). I 

26334 EXAMPLES I 

26335 None. I 

26336 Notes to Reviewers I 

26337 This section zvith side shading zvill not appear in the final copy. - Ed. I 

26338 There is a long example which could be included in the XRAT volume? I 

26339 APPLICATION USAGE I 

26340 These functions are part of the _POSIX_SPAWN option and need not be provided on all I 

26341 implementations. I 

26342 RATIONALE I 

26343 The FOSlXfork( ) function is difficult or impossible to implement without swapping or dynamic I 

26344 address translation for the following reasons: I 

26345 • Swapping is generally too slow for a realtime environment. I 

26346 • Dynamic address translation is not available everywhere POSIX might be useful. I 

26347 • Processes are too useful to simply option out of POSIX whenever it must run without I 

26348 address translation or other MMU services, I 

26349 POSIX needs process creation and file execution primitives that can be efficiently implemented I 

26350 without address translation or other MMU services. I 

26351 This function shall be called posix_spazvn(). A closely related function, posix_spazvnp(), is I 

26352 included for completeness. I 

26353 The posix_spazvn () function is implementable as a library routine, but both posix_spazvn () and I 

26354 posix_spazvnp() are designed as kernel operations. Also, although they may be an efficient I 

26355 replacement for many fork ()/ exec pairs, their goal is to provide useful process creation I 

26356 primitives for systems that have difficulty with fork(), not to provide drop-in replacements for I 

26357 fork ()/exec. I 

26358 This view of the role of posix_spazvn () and posix_spazvnp () influenced the design of their API. It I 

26359 does not attempt to provide the full functionality of fork () /exec in which arbitrary user-specified I 

26360 operations of any sort are permitted between the creation of the child process and the execution I 
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of the new process image; any attempt to reach that level would need to provide a programming I 
language as parameters. Instead, posix_spaivn () and posix_spawnp() are process creation I 
primitives like the Start_Process and Start_Process_Search Ada language bindings package I 
POSIX_Process_Primitives and also like those in many operating systems that are not UNIX I 
systems, but with some POSIX-specific additions. I 

To achieve its coverage goals, posix_spaivn () and posix_spawnp () have control of six types of I 
inheritance: file descriptors, process group ID, user and group ID, signal mask, scheduling, and I 
whether each signal ignored in the parent will remain ignored in the child, or be reset to its I 
default action in the child. I 

Control of file descriptors is required to allow an independently written child process image to I 
access data streams opened by and even generated or read by the parent process without being I 
specifically coded to know which parent files and file descriptors are to be used. Control of the I 
process group ID is required to control how the child process' job control relates to that of the I 
parent. I 

Control of the signal mask and signal defaulting is sufficient to support the implementation of I 

system( ). Although support for system () is not explicitly one of the goals for posix_spazvn () and I 

posix_spaivnp (), it is covered under the "at least 50%" coverage goal. I 

The intention is that the normal file descriptor inheritance across fork( ), the subsequent effect of I 
the specified spawn file actions, and the normal file descriptor inheritance across one of the exec I 
family of functions should fully specify open file inheritance. The implementation need make no I 
decisions regarding the set of open file descriptors when the child process image begins I 
execution, those decisions having already been made by the caller and expressed as the set of I 
open file descriptors and their FD_CLOEXEC flags at the time of the call and the spawn file I 

actions object specified in the call. We have been assured that in cases where the POSIX I 

Start_Process Ada primitives have been implemented in a library, this method of controlling file I 
descriptor inheritance may be implemented very easily. I 

We can identify several problems with posix_spawn{) and posix_spawnp{), but there does not I 
appear to be a solution that introduces fewer problems. Environment modification for child I 
process attributes not specifiable via the attrp or filejictions arguments must be done in the I 
parent process, and since the parent generally wants to save its context, it is more costly than I 
similar functionality with fork ()/exec. It is also complicated to modify the environment of a I 
multi-threaded process temporarily, since all threads must agree when it is safe for the I 
environment to be changed. However, this cost is only borne by those invocations of I 
posix_spawn{) and posix_spawnp() that use the additional functionality. Since extensive I 
modifications are not the usual case, and are particularly unlikely in time-critical code, keeping I 
much of the environment control out of posix_spazvn () and posix_spawnp () is appropriate design. I 

The posix_spazvn () and posix_spazvnp () functions do not have all the power oi fork ()/exec. This is I 
to be expected. The fork () function is a wonderfully powerful operation. We do not expect to I 
duplicate its functionality in a simple, fast function with no special hardware requirements. It is I 
worth noting that posix_spawn{) and posix_spaivnp () are very similar to the process creation I 
operations on many operating systems that are not UNIX systems. I 
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Requirements 

The requirements for posix_spaivn () and posix_spawnp () are: 

• They must be implementable without an MMU or unusual hardware. 

• They must be compatible with existing POSIX standards. 

Additional goals are: 

• They should be efficiently implementable. 

• They should be able to replace at least 50% of typical executions of fork (). 

• A system with posix_spaivn () and posix_spazvnp () and without fork( ) should be useful, at least 
for realtime applications. 

• A system with fork() and the exec family should be able to implement posix_spaivn () and 
posix_spawnp () as library routines. 

Two-Syntax 

POSIX exec has several calling sequences with approximately the same functionality. These 
appear to be required for compatibility with existing practice. Since the existing practice for the 
posix_spawn*() functions is otherwise substantially unlike POSIX, we feel that simplicity 
outweighs compatibility. There are, therefore, only two names for the posix_spawn*{ ) functions. 

The parameter list does not differ between posix_spawn() and posix_spaivnp(); posix_spawnp () 
interprets the second parameter more elaborately than posix_spaivn (). 

Compatibility with POSIX.5 POSIX_Process_Primitives.Start_Process 

The Start_Process and Start_Process_Search procedures from the Ada language binding to POSIX.1 
encapsulate fork() and exec functionality in a manner similar to that of posix_spawn () and 
posix_spawnp{). Originally, in keeping with our simplicity goal, the standard developers had 
limited the capabilities of posix_spawn() and posix_spaivnp () to a subset of the capabilities of 
Start_Process and Start_Process_Search ; certain non-default capabilities were not supported. 
However, based on suggestions by the ballot group to improve file descriptor mapping or drop 
it, and on the advice of an Ada Language Bindings working group member, the standard 
developers decided that posix_spazvn () and posix_spaivnp () should be sufficiently powerful to 
implement Start_Process and Start_Process_Search. The rationale is that if the Ada language 
binding to such a primitive had already been approved as an IEEE standard, there can be little 
justification for not approving the functionally-equivalent parts of a C binding. The only three 
capabilities provided by posix_spaivn () and posix_spaivnp () that are not provided by Start_Process 
and Start_Process_Search are optionally specifying the child's process group ID, the set of signals 
to be reset to default signal handling in the child process, and the child's scheduling policy and 
parameters. 

For the Ada language binding for Start_Process to be implemented with posix_spawn(), that 
binding would need to explicitly pass an empty signal mask and the parent's environment to 
posix_spawn() whenever the caller of Start_Process allowed these arguments to default, since 
posix_spazvn () does not provide such defaults. The ability of Start_Process to mask user-specified 
signals during its execution is functionally unique to the Ada language binding and must be 
dealt with in the binding separately from the call to posix_spawn (). 
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Process Group 

The process group inheritance field can be used to join the child process with an existing process 
group. By assigning a value of zero to the spazvn-pgroup attribute of the object referenced by 
attrp, the setpgid( ) mechanism will place the child process in a new process group. 

Threads 

Without the posix_spawn{) and posix_spazvnp () functions, systems without address translation 
can still use threads to give an abstraction of concurrency. In many cases, thread creation 
suffices, but it is not always a good substitute. The posix_spazvn () and posix_spawnp () functions 
are considerably "heavier" than thread creation. Processes have several important attributes that 
threads do not. Even without address translation, a process may have base-and-bound memory 
protection. Each process has a process environment including security attributes and file 
capabilities, and powerful scheduling attributes. Processes abstract the behavior of non- 
uniform-memory-architecture multi-processors better than threads, and they are more 
convenient to use for activities that are not closely linked. 

The posix_spaivn () and posix_spawnp () functions may not bring support for multiple processes to 
every configuration. Process creation is not the only piece of operating system support required 
to support multiple processes. The total cost of support for multiple processes may be quite high 
in some circumstances. Existing practice shows that support for multiple processes is 
uncommon and threads are common among "tiny kernels". There should, therefore, probably 
continue to be AEPs for operating systems with only one process. 

Asynchronous Error Notification 

A library implementation of posix_spazvn () or posix_spazvnp () may not be able to detect all 
possible errors before it forks the child process. IEEE Std. 1003.1-200x provides for an error 
indication returned from a child process which could not successfully complete the spawn 
operation via a special exit status which may be detected using the status value returned by 
wait () and ivaitpid (). 

The stat_val interface and the macros used to interpret it are not well suited to the purpose of 
returning API errors, but they are the only path available to a library implementation. Thus, an 
implementation may cause the child process to exit with exit status 127 for any error detected 
during the spawn process after the posix_spaivn () or posix_spawnp () function has successfully 
returned. 

The standard developers had proposed using two additional macros to interpret stat_val . The 
first, WIFSPAWNFAIL, would have detected a status that indicated that the child exited because 
of an error detected during the posix_spazvn() or posix_spawnp () operations rather than during 
actual execution of the child process image; the second, WSPAWNERRNO, would have 
extracted the error value if WIFSPAWNFAIL indicated a failure. Unfortunately, the ballot group 
strongly opposed this because it would make a library implementation of posix_spawn{) or 
posix_spawnp () dependent on kernel modifications to zvaitpid() to be able to embed special 
information in stat_val to indicate a spawn failure. 

The 8 bits of child process exit status that are guaranteed by IEEE Std. 1003.1-200x to be 
accessible to the waiting parent process are insufficient to disambiguate a spawn error from any 
other kind of error that my be returned by an arbitrary process image. No other bits of the exit 
status are required to be visible in stat_val, so these macros could not be strictly implemented at 
the library level. Reserving an exit status of 127 for such spawn errors is consistent with the use 
of this value by system () and popen() to signal failures in these operations that occur after the 
function has returned but before a shell is able to execute. The exit status of 127 does not 
uniquely identify this class of error, nor does it provide any detailed information on the nature 
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26489 of the failure. Note that a kernel implementation of posix_spaivn () or posix_spawnp () is permitted I 

26490 (and encouraged) to return any possible error as the function value, thus providing more I 

26491 detailed failure information to the parent process. I 

26492 Thus, no special macros are available to isolate asynchronous posix_spaivn () or posix_spaivnp () I 

26493 errors. Instead, errors detected by the posix_spaivn () or posix_spaivnp () operations in the context I 

26494 of the child process before the new process image executes are reported by setting the child's I 

26495 exit status to 127. The calling process may use the WIFEXITED and WEXITSTATUS macros on I 

26496 the stat_val stored by the wait () or ivaitpid () functions to detect spawn failures to the extent that I 

26497 other status values with which the child process image may exit (before the parent can I 

26498 conclusively determine that the child process image has begun execution) are distinct from exit I 

26499 status 127. I 

26500 FUTURE DIRECTIONS I 

26501 None. I 

26502 SEE ALSO I 

26503 alarm{), chmod{), close (), dup(), _exit (), exec,fcntl ( ),fork {), kill (), open (), I 

26504 posix_spaivn_file_actions_addclose {), posix_spawn_file_actions_adddup2 (), I 

26505 posix_spawn_file_actions_addopen (), posix_spaivn_file_actions_destroy (), I 

26506 posix_spazvn_file_actions_init (), posix_spazvnattr_destroy (), posix_spawnattr_init (), I 

26507 posix_spawnattr_getdefau.lt (), posix_spaivnattr_getflags(), posix_spaivnattr_getpgronp(), I 

26508 posix_spawnattr_getschedparam {), posix_spawnattr_getschedpolicy (), posix_spawnattr_getsigmask (), I 

26509 posix_spawnattr_setdefault (), posix_spaivnattr_setflags (), posix_spaivnattr_setpgroup(), I 

26510 posix_spawnattr_setschedparam (), posix_spawnattr_setschedpolicy {), posix_spawnattr_setsigmask (), I 

26511 sched_setparam (), sched_setschednler( ), setpgid( ), setiud( ), stat( ), times(), ivait (), the System I 

26512 Interface Definitions volume of IEEE Std. 1003.1-200x, <spawn.h> I 

26513 CHANGE HISTORY I 

26514 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 

26515 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. I 
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26516 NAME 

26517 posix_spawn_file_actions_addclose, posix_spawn_file_actions_addopen — close and open 

26518 spawn file actions object (REALTIME) 

26519 SYNOPSIS 

26520 SPN #include <spawn.h> 

26521 

26522 

26523 

26524 

26525 

26526 

26527 DESCRIPTION 

26528 A spawn file actions object is of type posix_spawn_file_actions_t (defined in <spawn.h>) and is 

26529 used to specify a series of actions to be performed by a posix_spawn() or posix_spawnp{) 

26530 operation in order to arrive at the set of open file descriptors for the child process given the set of 

26531 open file descriptors of the parent. IEEE Std. 1003.1-200x does not define comparison or 

26532 assignment operators for the type posix_spawn_file_actions_t. 

26533 A spawn file actions object, when passed to posix_spazvn () or posix_spaivnp(), shall specify how 

26534 the set of open file descriptors in the calling process is transformed into a set of potentially open 

26535 file descriptors for the spawned process. This transformation shall be as if the specified sequence 

26536 of actions was performed exactly once, in the context of the spawned process (prior to execution 

26537 of the new process image), in the order in which the actions were added to the object; 

26538 additionally, when the new process image is executed, any file descriptor (from this new set) 

26539 which has its FD_CLOEXEC flag set will be closed (see posix_spaivn ()). 

26540 The posix_spaivn_file_actions_addclose( ) function adds a close action to the object referenced by 

26541 file_actions that will cause the file descriptor fildes to be closed (as if close(fildes) had been called) 

26542 when a new process is spawned using this file actions object. 

26543 The posix_spawn_file_actions_addopen () function adds an open action to the object referenced by 

26544 file_actions that will cause the file named by path to be opened (as if open(path, oflag, mode) had 

26545 been called, and the returned file descriptor, if not fildes, had been changed to fildes) when a new 

26546 process is spawned using this file actions object. If fildes was already an open file descriptor, it 

26547 shall be closed before the new file is opened. 

26548 RETURN 

26549 Upon successful completion, these functions shall return zero; otherwise, an error number shall 

26550 be returned to indicate the error. 

26551 ERRORS 

26552 These functions shall fail if: 

26553 [EBADF] The value specified by fildes is negative or greater than or equal to 

26554 {OPEN_MAX}. 

26555 These functions may fail if: 

26556 [EINVAL] The value specified by filejictions is invalid. 

26557 [ENOMEM] Insufficient memory exists to add to the spawn file actions object. 

26558 It shall not be considered an error for th e fildes argument passed to these functions to specify a 

26559 file descriptor for which the specified operation could not be performed at the time of the call. 

26560 Any such error will be detected when the associated file actions object is later used during a 

26561 posix_spaivn () or posix_spaivnp () operation. 


int posix_spawn_file_actions_addclose(posix_spawn_file_actions_t * 
file_actions, int fildes) ; 

int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t * 
file_actions, int fildes, const char *path, int oflag, 
mode_t mode) ; 
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26562 EXAMPLES 

26563 None. 

26564 APPLICATION USAGE 

26565 These functions are part of the _POSIX_SPAWN option and need not be provided on all 

26566 implementations. 

26567 RATIONALE 

26568 A spawn file actions object may be initialized to contain an ordered sequence of close (), dup2{ ), 

26569 and open() operations to be used by posix_spaivn () or posix_spazvnp ( ) to arrive at the set of open 

26570 file descriptors inherited by the spawned process from the set of open file descriptors in the 

26571 parent at the time of the posix_spawn{) or posix_spawnp () call. It had been suggested that the 

26572 close () and dup2() operations alone are sufficient to rearrange file descriptors, and that files 

26573 which need to be opened for use by the spawned process can be handled either by having the 

26574 calling process open them before the posix_spazvn () or posix_spawnp () call (and close them after), 

26575 or by passing file names to the spawned process (in argv) so that it may open them itself. The 

26576 standard developers recommend that applications use one of these two methods when practical, 

26577 since detailed error status on a failed open operation is always available to the application this 

26578 way. However, the standard developers feel that allowing a spawn file actions object to specify 

26579 open operations is still appropriate because: 

26580 1. It is consistent with equivalent POSIX.5 (Ada) functionality. 

26581 2. It supports the I/O redirection paradigm commonly employed by POSIX programs 

26582 designed to be invoked from a shell. When such a program is the child process, it may not 

26583 be designed to open files on its own. 

26584 3. It allows file opens that might otherwise fail or violate file ownership/access rights if 

26585 executed by the parent process. 

26586 Regarding 2. above, note that the spawn open file action provides to posix_spawn() and 

26587 posix_spazvnp () the same capability that the shell redirection operators provide to system( ), only 

26588 without the intervening execution of a shell; for example: 

26589 system ("myprog <filel 3<file2"); 

26590 Regarding 3. above, note that if the calling process needs to open one or more files for access by 

26591 the spawned process, but has insufficient spare file descriptors, then the open action is necessary 

26592 to allow the open () to occur in the context of the child process after other file descriptors have 

26593 been closed (that must remain open in the parent). 

26594 Additionally, if a parent is executed from a file having a "set-user-id" mode bit set and the 

26595 POSIX_SPAWN_RESETIDS flag is set in the spawn attributes, a file created within the parent 

26596 process will (possibly incorrectly) have the parent's effective user ID as its owner, whereas a file 

26597 created via an open() action during posix_spaivn () or posix_spawnp () will have the parent's real 

26598 ID as its owner; and an open by the parent process may successfully open a file to which the real 

26599 user should not have access or fail to open a file to which the real user should have access. 

26600 File Descriptor Mapping 

26601 The standard developers had originally proposed using an array which specified the mapping of 

26602 child file descriptors back to those of the parent. It was pointed out by the ballot group that it is 

26603 not possible to reshuffle file descriptors arbitrarily in a library implementation of posix_spazvn () 

26604 or posix_spazvnp () without provision for one or more spare file descriptor entries (which simply 

26605 may not be available). Such an array requires that an implementation develop a complex 

26606 strategy to achieve the desired mapping without inadvertently closing the wrong file descriptor 

26607 at the wrong time. 
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26608 It was noted by a member of the Ada Language Bindings working group that the approved Ada I 

26609 Language Start_Process family of POSIX process primitives use a caller-specified set of file I 

26610 actions to alter the normal fork()/exec semantics for inheritance of file descriptors in a very I 

26611 flexible way, yet no such problems exist because the burden of determining how to achieve the I 

26612 final file descriptor mapping is completely on the application. Furthermore, although the file I 

26613 actions interface appears frightening at first glance, it is actually quite simple to implement in I 

26614 either a library or the kernel. I 

26615 FUTURE DIRECTIONS I 

26616 None. I 

26617 SEE ALSO I 

26618 close(), dnp(), open(), posix_spawn(), posix_spawn_file_actions_adddup2{), I 

26619 posix_spazvn_file_actions_destroy() / posix_spawnp{), the System Interface Definitions volume of I 

26620 IEEE Std. 1003.1-200x, <spawn.h> I 

26621 CHANGE HISTORY I 

26622 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 

26623 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. I 
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26624 NAME 

26625 posix_spawn_file_actions_adddup2 — add to spawn file actions object (REALTIME) 

26626 SYNOPSIS 

26627 SPN #include <spawn.h> 

26628 int posix_spawn_file_actions_adddup2(posix_spawn_file_actions_t * 

26629 file_actions , int fildes, int newfildes) ; 

26630 

26631 DESCRIPTION 

26632 A spawn file actions object is as defined in posix_spaivn_file_actions_addclose (). 

26633 The posix_spawn_file_actions_adddup2 () function adds a dupl () action to the object referenced by 

26634 file_actions that will cause the file descriptor fildes to be duplicated as newfildes (as if dnp2 (fildes, 

26635 newfildes ) had been called) when a new process is spawned using this file actions object. 

26636 RETURN 

26637 Upon successful completion, the posix_spawn_file_actions_adddup2() function shall return zero; 

26638 otherwise, an error number shall be returned to indicate the error. 

26639 ERRORS 

26640 The posix_spawn_file_actions_adddup2 () function shall fail if: 

26641 [EBADF] The value specified by fildes is negative or greater than or equal to 

26642 {OPEN_MAX}. 

26643 [ENOMEM] Insufficient memory exists to add to the spawn file actions object. 

26644 The posix_spawn_file_actions_adddup2 () function may fail if: 

26645 [EINVAL] The value specified by file_actions is invalid. 

26646 It shall not be considered an error for the fildes argument passed to the 

26647 posix_spawn_file_actions_adddup2 () function to specify a file descriptor for which the specified 

26648 operation could not be performed at the time of the call. Any such error will be detected when 

26649 the associated file actions object is later used during a posix_spawn() or posix_spaivnp () 

26650 operation. 

26651 EXAMPLES 

26652 None. 

26653 APPLICATION USAGE 

26654 The posix_spawn_file_actions_adddup2 () function is part of the _POSIX_SPAWN option and need 

26655 not be provided on all implementations. 

26656 RATIONALE 

26657 Refer to the RATIONALE in posix_spawn_file_actions_addclose( ). 

26658 FUTURE DIRECTIONS 

26659 None. 

26660 SEE ALSO 

26661 dup(), posix_spawn(), posix_spawn_file_actions_addclose(), posix_spazvn_file_actions_destroy(), 

26662 posix_spazvnp(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <spawn.h> 

26663 CHANGE HISTORY 

26664 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 

26665 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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26666 NAME 

26667 posix_spawn_file_actions_addopen — open spawn file actions object (REALTIME) 

26668 SYNOPSIS 

26669 SPN #include <spawn.h> 

26670 

26671 

26672 

26673 

26674 DESCRIPTION 

26675 Refer to posix_spaivn_file_actions_addclose (). 


int posix_spawn_file_actions_addopen(posix_spawn_file_actions_t * 
file_actions, int fildes, const char *path, int oflag, 
mode_t mode) ; 
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26676 NAME 

26677 posix_spawn_file_actions_destroy, posix_spawn_file_actions_init — destroy and initialize 

26678 spawn file actions object (REALTIME) 

26679 SYNOPSIS 

26680 SPN #include <spawn.h> 

26681 
26682 

26683 

26684 

26685 

26686 DESCRIPTION 

26687 A spawn file actions object is as defined in posix_spaivn_file_actions_addclose( ). 

26688 The posix_spazvn_file_actions_destroy( ) function destroys the object referenced by file_actions ; the 

26689 object becomes, in effect, uninitialized. An implementation may cause 

26690 posix_spaivn_file_actions_destroy( ) to set the object referenced by file_actions to an invalid value. A 

26691 destroyed spawn file actions object can be reinitialized using posix_spawn_file_actions_init{ ); the 

26692 results of otherwise referencing the object after it has been destroyed are undefined. 

26693 The posix_spaivn_file_actions_init() function initializes the object referenced by file_actions to 

26694 contain no file actions for posix_spcnvn () or posix_spaivnp () to perform. 

26695 RETURN 

26696 Upon successful completion, these functions shall return zero; otherwise, an error number shall 

26697 be returned to indicate the error. 

26698 ERRORS 

26699 The posix_spawnjT.le_actions_in.it { ) function shall fail if: 

26700 [ENOMEM] Insufficient memory exists to initialize the spawn file actions object. 

26701 The posix_spazvn_file_actions_destroy( ) function may fail if: 

26702 [EINVAL] The value specified by file_actions is invalid. 

26703 EXAMPLES 

26704 None. 

26705 APPLICATION USAGE 

26706 These functions are part of the _POSIX_SPAWN option and need not be provided on all 

26707 implementations. 

26708 RATIONALE 

26709 Refer to the RATIONALE in posix_spaivn_file_actions_addclose (). 

26710 FUTURE DIRECTIONS 

26711 None. 

26712 SEE ALSO 

26713 posix_spaivn (), posix_spaivnp (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

26714 <spawn.h> 

26715 CHANGE HISTORY 

26716 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 

26717 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 


int posix_spawn_file_actions_destroy(posix_spawn_file_actions_t * 
file_actions) ; 

int posix_spawn_file_actions_init(posix_spawn_file_actions_t * 
file_actions) ; 
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26718 NAME 

26719 posix_spawn_file_actions_init — initialize spawn file actions object (REALTIME) 

26720 SYNOPSIS 

26721 SPN #include <spawn.h> 

26722 int posix_spawn_file_actions_init(posix_spawn_file_actions_t * 

26723 file_actions) ; 

26724 

26725 DESCRIPTION 

26726 Refer to posix_spaivn_file_actions_destroy (). 
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26727 NAME 

26728 posix_spawnattr_destroy, posix_spawnattr_init — destroy and initialize spawn attributes object 

26729 (REALTIME) 

26730 SYNOPSIS 

26731 SPN #include <spawn.h> 

26732 

26733 

26734 

26735 DESCRIPTION 

26736 A spawn attributes object is of type posix_spawnattr_t (defined in <spawn.h>) and is used to 

26737 specify the inheritance of process attributes across a spawn operation. IEEE Std. 1003.1-200x 

26738 does not define comparison or assignment operators for the type posix_spawnattr_t. 

26739 The posix_spawnattr_destroy{ ) function destroys a spawn attributes object. The effect of 

26740 subsequent use of the object is undefined until the object is reinitialized by another call to 

26741 posix_spawnattr_init (). An implementation may cause posix_spazvnattr_destroy( ) to set the object 

26742 referenced by attr to an invalid value. 

26743 The posix_spawnattr_init{ ) function initializes a spawn attributes object attr with the default 

26744 value for all of the individual attributes used by the implementation. 

26745 Each implementation shall document the individual attributes it uses and their default values 

26746 unless these values are defined by IEEE Std. 1003.1-200x. Attributes not defined by 

26747 IEEE Std. 1003.1-200x, their default values, and the names of the associated functions to get and 

26748 set those attribute values are implementation-dependent. 

26749 The resulting spawn attributes object (possibly modified by setting individual attribute values), 

26750 is used to modify the behavior of posix_spawn{) or posix_spazvnp(). After a spawn attributes 

26751 object has been used to spawn a process by a call to a posix_spawn() or posix_spawnp(), any 

26752 function affecting the attributes object (including destruction) does not affect any process that 

26753 has been spawned in this way. 

26754 The effect of initializing an already initialized spawn file actions object is undefined. 

26755 RETURN VALUE 

26756 Upon successful completion, posix_spaivnattr_destroy() and posix_spawnattr_init() shall return 

26757 zero; otherwise, an error number shall be returned to indicate the error. 

26758 ERRORS 

26759 The posix_spawnattr_init( ) function shall fail if: 

26760 [ENOMEM] Insufficient memory exists to initialize the spawn attributes object. 

26761 The posix_spawnattr_destroy() function may fail if: 

26762 [EINVAL] The value specified by attr is invalid. 


int posix_spawnattr_destroy(posix_spawnattr_t *attr); 
int posix_spawnattr_init(posix_spawnattr_t *attr) ; 
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26763 

26764 

26765 

26766 

26767 

26768 

26769 

26770 

26771 

26772 

26773 

26774 

26775 

26776 

26777 

26778 

26779 

26780 

26781 

26782 

26783 

26784 

26785 

26786 

26787 

26788 

26789 


EXAMPLES 

None. 

APPLICATION USAGE 

These functions are part of the _POSIX_SPAWN option and need not be provided on all 
implementations. 

RATIONALE 

The original spawn interface proposed in IEEE Std. 1003.1-200x defined the attributes that 
specify the inheritance of process attributes across a spawn operation as a structure. In order to 
be able to separate optional individual attributes under their appropriate options (that is, the 
spawn-schedparam and spawn-schedpolicy attributes depending upon the Process Scheduling 
option), and also for extensibility and consistency with the newer POSIX interfaces, the 
attributes interface has been changed to an opaque data type. This interface now consists of the 
type posix_spawnattr_t, representing a spawn attributes object, together with associated 
functions to initialize or destroy the attributes object, and to set or get each individual attribute. 
Although the new object-oriented interface is more verbose than the original structure, it is 
simple to use, more extensible, and easy to implement. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

posix_spazvn (), posix_spazvnattr_getdefaidt (), posix_spaivnattr_getflags(), 

posix_spazvnattr_getpgronp (), posix_spaumattr_getschedparam (), posix_spaivnattr_getschedpolicy (), 
posix_spazvnattr_getsigmask (), posix_spawnattr_setdefault (), posix_spaivnattr_setflags (), 
posix_spawnattr_setpgroup(), posix_spawnattr_setsigmask (), posix_spawnattr_setschedpolicy (), 
posix_spawnattr_setschedparam (), posix_spawnp(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <spawn.h> 

CHANGE HISTORY 

First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 
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26790 NAME 

26791 posix_spawnattr_getdefault, posix_spawnattr_setdefault — get and set spawn-sigdefault 

26792 attribute of spawn attributes object (REALTIME) 

26793 SYNOPSIS 

26794 SPN 

26795 

26796 

26797 

26798 

26799 

26800 

26801 DESCRIPTION 

26802 The spawn-sigdefault attribute represents the set of signals to be forced to default signal handling 

26803 in the new process image (if POSIX_SPAWN_SETSIGDEF is set in the spaivn-flags attribute) by a 

26804 spawn operation. The default value of this attribute shall be an empty signal set. 

26805 The posix_spawnattr_getdefaidt( ) function obtains the value of the spawn-sigdefault attribute from 

26806 the attributes object referenced by attr. 

26807 The posix_spawnattr_setdefault{ ) function is used to set the spawn-sigdefault attribute in an 

26808 initialized attributes object referenced by attr. 

26809 RETURN VALUE 

26810 Upon successful completion, posix_spawnattr_getdefaidt( ) shall return zero and store the value of 

26811 the spawn-sigdefault attribute of attr into the object referenced by the sigdefault parameter; 

26812 otherwise, an error number shall be returned to indicate the error. 

26813 Upon successful completion, posix_spazvnattr_setdefaidt() shall return zero; otherwise, an error 

26814 number shall be returned to indicate the error. 

26815 ERRORS 

26816 These functions may fail if: 

26817 [EINVAL] The value specified by attr is invalid. 

26818 The posix_spawnattr_setdefault() function may fail if: 

26819 [EINVAL] The value of the attribute being set is not valid. 

26820 EXAMPLES 

26821 None. 

26822 APPLICATION USAGE 

26823 These functions are part of the _POSIX_SPAWN option and need not be provided on all 

26824 implementations. 

26825 RATIONALE 

26826 None. 

26827 FUTURE DIRECTIONS 

26828 None. 

26829 SEE ALSO 

26830 posix_spazvn (), posix_spazvnattr_destroy( ), posix_spawnattr_init {), posix_spazvnattr_getflags(), 

26831 posix_spaivnattr_getpgroup (), posix_spawnattr_getschedparam (), posix_spawnattr_getschedpolicy (), 

26832 posix_spawnattr_getsigmask( ), posix_spazvnattr_setflags (), posix_spawnattr_setpgroup (), 

26833 posix_spawnattr_setschedparam( ), posix_spawnattr_setschedpolicy( ), posix_spawnattr_setsigmask( ), 


#include <signal.h> 

#include <spawn.h> 

int posix_spawnattr_getdefault(const posix_spawnattr_t *attr, 
sigset_t * sigdefault) ; 

int posix_spawnattr_setdefault(posix_spawnattr_t *attr, 
const sigset_t * sigdefault) ; 
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26834 posix_spaivnp(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <signal.h>, 

26835 <spawn.h> 

26836 CHANGE HISTORY 

26837 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 
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26838 NAME 

26839 posix_spawnattr_getflags, posix_spawnattr_setflags — get and set spawn-flags attribute of 

26840 spawn attributes object (REALTIME) 

26841 SYNOPSIS 

26842 SPN #include <spawn.h> 

26843 

26844 

26845 

26846 

26847 DESCRIPTION 

26848 The spaivn-flags attribute is used to indicate which process attributes are to be changed in the 

26849 new process image when invoking posix_spaivn () or posix_spaivnp(). It is the bitwise-inclusive 

26850 OR of zero or more of the flags POSIX_SPAWN_RESETIDS, POSIX_SPAWN_SETPGROUP, 

26851 POSIX_SPAWN_SETSIGDEF, and POSIX_SPAWN_SETSIGMASK. In addition, if the Process 

26852 Scheduling option is supported, the flags POSIX_SPAWN_SETSCHEDPARAM and 

26853 POSIX_SPAWN_SETSCHEDULER shall also be supported. These flags are defined in 

26854 <spawn.h>. The default value of this attribute shall be with no flags set. 

26855 The posix_spazvnattr_getflags() function obtains the value of the spaivn-flags attribute from the 

26856 attributes object referenced by attr. 

26857 The posix_spaivnattr_setflags() function is used to set the spaivn-flags attribute in an initialized 

26858 attributes object referenced by attr. 

26859 RETURN VALUE 

26860 Upon successful completion, posix_spaivnattr_getflags() shall return zero and store the value of 

26861 the spawn-flags attribute of attr into the object referenced by the flags parameter; otherwise, an 

26862 error number shall be returned to indicate the error. 

26863 Upon successful completion, posix_spaivnattr_setflags() shall return zero; otherwise, an error 

26864 number shall be returned to indicate the error. 

26865 ERRORS 

26866 These functions may fail if: 

26867 [EINVAL] The value specified by attr is invalid. 

26868 The posix_spaivnattr_setflags( ) function may fail if: 

26869 [EINVAL] The value of the attribute being set is not valid. 

26870 EXAMPLES 

26871 None. 

26872 APPLICATION USAGE 

26873 These functions are part of the _POSIX_SPAWN option and need not be provided on all 

26874 implementations. 

26875 RATIONALE 

26876 None. 

26877 FUTURE DIRECTIONS 

26878 None. 


int posix_spawnattr_getflags(const posix_spawnattr_t *attr, 
short * flags) ; 

int posix_spawnattr_setflags(posix_spawnattr_t *attr, short flags) ; 


System Interfaces, Issue 6 


857 





posix_spawnattr_getflags() 


System Interfaces 


26879 

26880 
26881 
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26883 

26884 

26885 

26886 
26887 


SEE ALSO 

posix_spawn (), ,-l .ds ;p posix_spawnattr_destroy {) on page 853, ,=1 .ds ;p posix_spawnattr_in.it () 
on page 867, posix_spawnattr_getdefaidt(), posix_spawnattr_getpgroup (), 

posix_spawnattr_getschedparam (), posix_spawnattr_getschedpolicy (), posix_spawnattr_getsigmask (), 
posix_spawnattr_setdefault {), posix_spaivnattr_setpgroup (), posix_spawnattr_setschedparam (), 
posix_spawnattr_setschedpolicy (), posix_spaivnattr_setsigmask (), posix_spawnp(), the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, <spawn.h> 

CHANGE HISTORY 

First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 
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26888 NAME 

26889 posix_spawnattr_getpgroup, posix_spawnattr_setpgroup — get and set spawn-pgroup attribute 

26890 of spawn attributes object (REALTIME) 

26891 SYNOPSIS 

26892 SPN #include <spawn.h> 

26893 

26894 

26895 

26896 

26897 DESCRIPTION 

26898 The spawn-pgroup attribute represents the process group to be joined by the new process image 

26899 in a spawn operation (if POSIX_SPAWN_SETPGROUP is set in the spazvn-flags attribute). The 

26900 default value of this attribute shall be zero. 

26901 The posix_spaivnattr_getpgroup () function obtains the value of the spawn-pgroup attribute from 

26902 the attributes object referenced by attr. 

26903 The posix_spawnattr_setpgroup() function is used to set the spawn-pgroup attribute in an 

26904 initialized attributes object referenced by attr. 

26905 RETURN VALUE 

26906 Upon successful completion, posix_spaiunattr_getpgroup( ) shall return zero and store the value of 

26907 the spawn-pgroup attribute of attr into the object referenced by the pgroup parameter; otherwise, 

26908 an error number shall be returned to indicate the error. 

26909 Upon successful completion, posix_spawnattr_setpgroup() shall return zero; otherwise, an error 

26910 number shall be returned to indicate the error. 

26911 ERRORS 

26912 These functions may fail if: 

26913 [EINVAL] The value specified by attr is invalid. 

26914 The posix_spawnattr_setpgroup () function may fail if: 

26915 [EINVAL] The value of the attribute being set is not valid. 

26916 EXAMPLES 

26917 None. 

26918 APPLICATION USAGE 

26919 These functions are part of the _POSIX_SPAWN option and need not be provided on all 

26920 implementations. 

26921 RATIONALE 

26922 None. 

26923 FUTURE DIRECTIONS 

26924 None. 

26925 SEE ALSO 

26926 posix_spazvn (), posix_spazvnattr_destroy (), posix_spawnattr_init {), posix_spawnattr_getdefault (), 

26927 posix_spazvnattr_getflags(), posix_spawnattr_getschedparam (), posix_spazvnattr_getschedpolicy (), 

26928 posix_spawnattr_getsigmask (), posix_spazvnattr_setdefault {), posix_spawnattr_setflags (), 

26929 posix_spazunattr_setschedparam (), posix_spazunattr_setschedpolicy (), posix_spawnattr_setsigmask (), 

26930 posix_spazvnp(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <spawn.h> 


int posix_spawnattr_getpgroup(const posix_spawnattr_t *attr, 
pid_t *pgroup ); 

int posix_spawnattr_setpgroup(posix_spawnattr_t *attr, pid_t pgroup); 
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CHANGE HISTORY 

First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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26934 NAME 

26935 posix_spawnattr_getschedparam, posix_spawnattr_setschedparam — get and set spawn- 

26936 schedparam attribute of spawn attributes object (REALTIME) 

26937 SYNOPSIS 

26938 SPN PS 

26939 

26940 

26941 

26942 

26943 

26944 

26945 DESCRIPTION 

26946 The spawn-schedparam attribute represents the scheduling parameters to be assigned to the new 

26947 process image in a spawn operation (if POSIX_SPAWN_SETSCHEDULER or 

26948 POSIX_SPAWN_SETSCHEDPARAM is set in the spaivn-flags attribute). The default value of this 

26949 attribute is unspecified. 

26950 The posix_spawnattr_getschedparam( ) function obtains the value of the spawn-schedparam attribute 

26951 from the attributes object referenced by attr. 

26952 The posix_spawnattr_setschedparam( ) function is used to set the spawn-schedparam attribute in an 

26953 initialized attributes object referenced by attr. 

26954 RETURN VALUE 

26955 Upon successful completion, posix_spawnattr_getschedparam () shall return zero and store the 

26956 value of the spawn-schedparam attribute of attr into the object referenced by the schedparam 

26957 parameter; otherwise, an error number shall be returned to indicate the error. 

26958 Upon successful completion, posix_spawnattr_setschedparam () shall return zero; otherwise, an 

26959 error number shall be returned to indicate the error. 

26960 ERRORS 

26961 These functions may fail if: 

26962 [EINVAL] The value specified by attr is invalid. 

26963 The posix_spawnattr_setschedparam( ) function may fail if: 

26964 [EINVAL] The value of the attribute being set is not valid. 

26965 EXAMPLES 

26966 None. 

26967 APPLICATION USAGE 

26968 These functions are part of the _POSIX_SPAWN and _POSIX_PRIORITY_SCHEDULING 

26969 options and need not be provided on all implementations. 

26970 RATIONALE 

26971 None. 

26972 FUTURE DIRECTIONS 

26973 None. 

26974 SEE ALSO 

26975 posix_spazvn (), posix_spazvnattr_destroy (), posix_spaiunattr_init ( ), posix_spawnattr_getdefau.lt (), 

26976 posix_spazvnattr_getflags(), posix_spawnattr_getpgroup( ), posix_spazvnattr_getschedpolicy( ), 

26977 posix_spazvnattr_getsigmask( ), posix_spawnattr_setdefault( ), posix_spazvnattr_setflags( ), 


#include <sched.h> 

#include <spawn.h> 

int posix_spawnattr_getschedparam(const posix_spawnattr_t *attr, 
struct sched_param * schedparam) ; 
int posix_spawnattr_setschedparam(posix_spawnattr_t *attr, 
const struct sched_param * schedparam ); 
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26978 posix_spawnattr_setpgroup (), posix_spawnattr_setschedpolicy (), posix_spawnattr_setsigmask (), 

26979 posix_spaivnp (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <sched.h>, 

26980 <spawn.h> 

26981 CHANGE HISTORY 

26982 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 
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26983 NAME 

26984 posix_spawnattr_getschedpolicy, posix_spawnattr_setschedpolicy — get and set spawn- 

26985 schedpolicy attribute of spawn attributes object (REALTIME) 

26986 SYNOPSIS 

26987 SPN PS 

26988 

26989 

26990 

26991 

26992 

26993 

26994 DESCRIPTION 

26995 The spawn-schedpolicy attribute represents the scheduling policy to be assigned to the new 

26996 process image in a spawn operation (if POSIX_SPAWN_SETSCHEDULER is set in the spaivn- 

26997 flags attribute). The default value of this attribute is unspecified. 

26998 The posix_spaivnattr_getschedpolicy( ) function obtains the value of the spawn-schedpolicy attribute 

26999 from the attributes object referenced by attr. 

27000 The posix_spawnattr_setschedpolicy() function is used to set the spawn-schedpolicy attribute in an 

27001 initialized attributes object referenced by attr. 

27002 RETURN VALUE 

27003 Upon successful completion, posix_spazvnattr_getschedpolicy() shall return zero and store the 

27004 value of the spawn-schedpolicy attribute of attr into the object referenced by the schedpolicy 

27005 parameter; otherwise, an error number shall be returned to indicate the error. 

27006 Upon successful completion, posix_spawnattr_setschedpolicy{) shall return zero; otherwise, an 

27007 error number shall be returned to indicate the error. 

27008 ERRORS 

27009 These functions may fail if: 

27010 [EINVAL] The value specified by attr is invalid. 

27011 The posix_spawnattr_setschedpolicy( ) function may fail if: 

27012 [EINVAL] The value of the attribute being set is not valid. 

27013 EXAMPLES 

27014 None. 

27015 APPLICATION USAGE 

27016 These functions are part of the _POSIX_SPAWN and _POSIX_PRIORITY_SCHEDULING 

27017 options and need not be provided on all implementations. 

27018 RATIONALE 

27019 None. 

27020 FUTURE DIRECTIONS 

27021 None. 

27022 SEE ALSO 

27023 posix_spazvn (), posix_spazvnattr_destroy( ), posix_spaiunattr_init (), posix_spaivnattr_getdefanlt( ), 

27024 posix_spaivnattr_getflags (), posix_spawnattr_getpgronp (), posix_spawnattr_getschedparam (), 

27025 posix_spawnattr_getsigmask( ), posix_spawnattr_setdefault{ ), posix_spaivnattr_setflags( ), 

27026 posix_spazvnattr_setpgronp( ), posix_spawnattr_setschedparam( ), posix_spawnattr_setsigmask( ), 


#include <sched.h> 

#include <spawn.h> 

int posix_spawnattr_getschedpolicy(const posix_spawnattr_t *attr, 
int * schedpolicy) ; 

int posix_spawnattr_setschedpolicy(posix_spawnattr_t *attr, 
int schedpolicy) ; 


System Interfaces, Issue 6 


863 




posix_spawnattr_getschedpolicy() 


System Interfaces 


27027 posix_spazvnp(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <sched.h>, 

27028 <spawn.h> 

27029 CHANGE HISTORY 

27030 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 
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27031 NAME 

27032 posix_spawnattr_getsigmask, posix_spawnattr_setsigmask — get and set spawn-sigmask 

27033 attribute of spawn attributes object (REALTIME) 

27034 SYNOPSIS 

27035 SPN 

27036 

27037 

27038 

27039 

27040 

27041 

27042 DESCRIPTION 

27043 The spawn-sigmask attribute represents the signal mask in effect in the new process image of a 

27044 spawn operation (if POSIX_SPAWN_SETSIGMASK is set in the spazvn-flags attribute). The 

27045 default value of this attribute is unspecified. 

27046 The posix_spawnattr_getsigmask( ) function obtains the value of the spawn-sigmask attribute from 

27047 the attributes object referenced by attr. 

27048 The posix_spawnattr_setsigmask( ) function is used to set the spawn-sigmask attribute in an 

27049 initialized attributes object referenced by attr. 

27050 RETURN VALUE 

27051 Upon successful completion, posix_spawnattr_getsigmask( ) shall return zero and store the value 

27052 of the spawn-sigmask attribute of attr into the object referenced by the sigmask parameter; 

27053 otherwise, an error number shall be returned to indicate the error. 

27054 Upon successful completion, posix_spawnattr_setsigmask( ) shall return zero; otherwise, an error 

27055 number shall be returned to indicate the error. 

27056 ERRORS 

27057 These functions may fail if: 

27058 [EINVAL] The value specified by attr is invalid. 

27059 The posix_spawnattr_setsigmask( ) function may fail if: 

27060 [EINVAL] The value of the attribute being set is not valid. 

27061 EXAMPLES 

27062 None. 

27063 APPLICATION USAGE 

27064 These functions are part of the _POSIX_SPAWN option and need not be provided on all 

27065 implementations. 

27066 RATIONALE 

27067 None. 

27068 FUTURE DIRECTIONS 

27069 None. 

27070 SEE ALSO 

27071 posix_spawn (), posix_spazvnattr_destroy( ), posix_spawnattr_init{ ), posix_spawnattr_getdefault( ), 

27072 posix_spaivnattr_getflags (), posix_spawnattr_getpgronp (), posix_spawnattr_getschedparam (), 

27073 posix_spaivnattr_getschedpolicy( ), posix_spawnattr_setdefau.lt {), posix_spawnattr_setflags( ), 

27074 posix_spawnattr_setpgronp( ), posix_spawnattr_setschedparam( ), posix_spawnattr_setschedpolicy( ), 


#include <signal.h> 

#include <spawn.h> 

int posix_spawnattr_getsigmask(const posix_spawnattr_t *attr, 
sigset_t * sigmask) ; 

int posix_spawnattr_setsigmask(posix_spawnattr_t *attr, 
const sigset_t * sigmask ); 
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27075 posix_spaivnp(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <signal.h>, 

27076 <spawn.h> 

27077 CHANGE HISTORY 

27078 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 
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27079 NAME 

27080 posix_spawnattr_init — initialize spawn attributes object (REALTIME) 

27081 SYNOPSIS 

27082 SPN #include <spawn.h> 

27083 int posix_spawnattr_init (posix_spawnattr_t *attr) ; 

27084 

27085 DESCRIPTION 

27086 Refer to posix_spcnvnattr_destroy (). 


System Interfaces, Issue 6 


867 




posix_spawnattr_setdefault() 


System Interfaces 


27087 NAME 

27088 posix_spawnattr_setdefault — set spawn-sigdefault attribute of spawn attributes object 

27089 (REALTIME) 

27090 SYNOPSIS 

27091 SPN 

27092 

27093 

27094 

27095 

27096 DESCRIPTION 

27097 Refer to posixjspawnattr_getdefau.lt (). 


#include <signal.h> 

#include <spawn.h> 

int posix_spawnattr_setdefault(posix_spawnattr_t *attr, 
const sigset_t *sigdefault) ; 
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27098 NAME 

27099 posix_spawnattr_setflags — set spawn-flags attribute of spawn attributes object (REALTIME) 

27100 SYNOPSIS 

27101 SPN #include <spawn.h> 

27102 int posix_spawnattr_setflags(posix_spawnattr_t *attr, short flags) ; 

27103 

27104 DESCRIPTION 

27105 Refer to posix_spcnvnattr_getflags (). 
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27106 NAME 

27107 posix_spawnattr_setpgroup — set spawn-pgroup attribute of spawn attributes object 

27108 (REALTIME) 

27109 SYNOPSIS 

27110 SPN #include <spawn.h> 

27111 int posix_spawnattr_setpgroup(posix_spawnattr_t *attr, pid_t pgroup ); 

27112 

27113 DESCRIPTION 

27114 Refer to posix_spcnvnattr_getpgronp (). 
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27115 NAME 

27116 posix_spawnattr_setschedparam — set spawn-schedparam attribute of spawn attributes object 

27117 (REALTIME) 

27118 SYNOPSIS 

27119 SPN PS 

27120 

27121 

27122 

27123 

27124 DESCRIPTION 

27125 Refer to posix_spawnattr_getschedparam (). 


#include <sched.h> 

#include <spawn.h> 

int posix_spawnattr_setschedparam(posix_spawnattr_t *attr, 
const struct sched_param * schedparam ); 
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27126 NAME 

27127 posix_spawnattr_setschedpolicy — set spawn-schedpolicy attribute of spawn attributes object 

27128 (REALTIME) 

27129 SYNOPSIS 

27130 SPN PS 

27131 

27132 

27133 

27134 

27135 DESCRIPTION 

27136 Refer to posixjspawnattr_getschedpolicy (). 


#include <sched.h> 

#include <spawn.h> 

int posix_spawnattr_setschedpolicy(posix_spawnattr_t *attr, 
int schedpolicy) ; 
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27137 NAME 

27138 posix_spawnattr_setsigmask — set spawn-sigmask attribute of spawn attributes object 

27139 (REALTIME) 

27140 SYNOPSIS 

27141 SPN 

27142 

27143 

27144 

27145 

27146 DESCRIPTION 

27147 Refer to posix_spawnattr_getsigmask (). 


#include <signal.h> 

#include <spawn.h> 

int posix_spawnattr_setsigmask(posix_spawnattr_t *attr, 
const sigset_t *sigmask ); 
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27148 NAME 

27149 posix_spawnp — spawn a process (REALTIME) 

27150 SYNOPSIS 

27151 SPN #include <spawn.h> 

27152 

27153 

27154 

27155 

27156 

27157 DESCRIPTION 

27158 Refer to posix_spaivn(). 


int posix_spawnp(pid_t *pid, const char *file, 

const posix_spawn_file_actions_t *file_actions, 
const posix_spawnattr_t *attrp, char * const argv[] , 
char * const envp[]); 
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27159 NAME 

27160 posix_typed_mem_get_info — query typed memory information 

27161 SYNOPSIS 

27162 TYM #include <sys/mman.h> 

27163 int posix_typed_mem_get_info (int fildes, 

27164 struct posix_typed_mem_info *info) ; 

27165 

27166 DESCRIPTION 

27167 The posix_typed_mem_get_info() function returns, in the posix_tmi_length field of the 

27168 posix_typed_mem_info structure pointed to by info , the maximum length which may be 

27169 successfully allocated by the typed memory object designated by fildes. This maximum length 

27170 shall take into account the flag POSIX_TYPED_MEM_ ALLOC ATE or 

27171 POSIX_TYPED_MEM_ALLOCATE_CONTIG specified when the typed memory object 

27172 represented by fildes was opened. The maximum length is dynamic; therefore, the value returned 

27173 is valid only while the current mapping of the corresponding typed memory pool remains 

27174 unchanged. 

27175 If fildes represents a typed memory object opened with neither the 

27176 POSIX_TYPED_MEM_ALLOCATE flag nor the POSIX_TYPED_MEM_ALLOCATE_CONTIG 

27177 flag specified, the returned value of info.posix_tmi_length is unspecified. 

27178 The posix_typed_mem_get_info () function may return additional implementation-dependent 

27179 information in other fields of the posix_typed_mem_info structure pointed to by info . 

27180 If the memory object specified by fildes is not a typed memory object, then the behavior of this 

27181 function is undefined. 

27182 RETURN VALUE 

27183 Upon successful completion, the posix_typed_mem_get_info () function shall return zero; 

27184 otherwise, the corresponding error status value shall be returned. 

27185 ERRORS 

27186 The posix_typed_mem_get_info( ) function shall fail if: 

27187 [EBADF] The fildes argument is not a valid open file descriptor. 

27188 [ENODEV] Th e fildes argument is not connected to a memory object supported by this 

27189 function. 

27190 This function does not return an error code of [EINTR], 

27191 EXAMPLES 

27192 None. 

27193 APPLICATION USAGE 

27194 None. 

27195 RATIONALE 

27196 An application that needs to allocate a block of typed memory with length dependent upon the 

27197 amount of memory currently available must either query the typed memory object to obtain the 

27198 amount available, or repeatedly invoke mmap () attempting to guess an appropriate length. 

27199 While the latter method is existing practice with malloc(), it is awkward and imprecise. The 

27200 posix_typed_mem_get_info () function allows an application to immediately determine available 

27201 memory. This is particularly important for typed memory objects that may in some cases be 

27202 scarce resources. Note that when a typed memory pool is a shared resource, some form of 

27203 mutual exclusion or synchronization may be required while typed memory is being queried and 
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27204 allocated to prevent race conditions. 

27205 The existing fstat() function is not suitable for this purpose. We realize that implementations 

27206 may wish to provide other attributes of typed memory objects (for example, alignment 

27207 requirements, page size, and so on). Th e function returns a structure which is not 

27208 extensible and, furthermore, contains substantial information that is inappropriate for typed 

27209 memory objects. 

27210 FUTURE DIRECTIONS 

27211 None. 

27212 SEE ALSO 

27213 mmap(), posix_typed_mem_open (), the System Interface Definitions volume of 

27214 IEEE Std. 1003.1-200x, <sys/mman.h> 

27215 CHANGE HISTORY 

27216 First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. 
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27217 NAME 

27218 posix_typed_mem_open — open a typed memory object 

27219 SYNOPSIS 

27220 TYM #include <sys/mman.h> 

27221 int posix_typed_mem_open (const char *name, int of lag, int tflag) ; 

27222 

27223 DESCRIPTION 

27224 The posix_typed_mem_open () function establishes a connection between the typed memory object 

27225 specified by the string pointed to by name and a file descriptor. It creates an open file description 

27226 that refers to the typed memory object and a file descriptor that refers to that open file 

27227 description. The file descriptor is used by other functions to refer to that typed memory object. It 

27228 is unspecified whether the name appears in the file system and is visible to other functions that 

27229 take path names as arguments. The name argument shall conform to the construction rules for a 

27230 path name. If name begins with the slash character, then processes calling 

27231 posix_typed_mem_open ( ) with the same value of name shall refer to the same typed memory 

27232 object. If name does not begin with the slash character, the effect is implementation-dependent. 

27233 The interpretation of slash characters other than the leading slash character in name is 

27234 implementation-dependent. 

27235 Each typed memory object supported in a system is identified by a name which specifies not 

27236 only its associated typed memory pool, but also the path or port by which it is accessed. That is, 

27237 the same typed memory pool accessed via several different ports has several different 

27238 corresponding names. The binding between names and typed memory objects is established in 

27239 an implementation-dependent manner. Unlike shared memory objects, there is ordinarily no 

27240 way for a program to create a typed memory object. 

27241 The value of tflag determines how the typed memory object behaves when subsequently 

27242 mapped by calls to mmap(). At most, one of the following flags defined in <sys/mman.h> may 

27243 be specified: 

27244 POSIX_TYPED_MEM_ALLOCATE 

27245 Allocate on mmap (). 

27246 POSIX_TYPED_MEM_ALLOCATE_CONTIG 

27247 Allocate contiguously on mmap (). 

27248 POSIX_TYPED_MEM_MAP_ALLOCATABLE 

27249 Map on mmap (), without affecting allocatability. 

27250 If tflag has the flag POSIX_TYPED_MEM_ ALLOC ATE specified, any subsequent call to mmap() 

27251 using the returned file descriptor shall result in allocation and mapping of typed memory from 

27252 the specified typed memory pool. The allocated memory may be a contiguous previously 

27253 unallocated area of the typed memory pool or several non-contiguous previously unallocated 

27254 areas (mapped to a contiguous portion of the process address space). If tflag has the flag 

27255 POSIX_TYPED_MEM_ALLOCATE_CONTIG specified, any subsequent call to mmap () using the 

27256 returned file descriptor shall result in allocation and mapping of a single contiguous previously 

27257 unallocated area of the typed memory pool (also mapped to a contiguous portion of the process 

27258 address space). If tflag has none of the flags POSIX_TYPED_MEM_ALLOCATE or 

27259 POSIX_TYPED_MEM_ALLOCATE_CONTIG specified, any subsequent call to mmap () using the 

27260 returned file descriptor shall map an application-chosen area from the specified typed memory 

27261 pool such that this mapped area becomes unavailable for allocation until unmapped by all 

27262 processes. If tflag has the flag POSIX_TYPED_MEM_MAP_ALLOCATABLE specified, any 

27263 subsequent call to mmap () using the returned file descriptor shall map an application-chosen 

27264 area from the specified typed memory pool without an effect on the availability of that area for 
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27265 allocation; that is, mapping such an object leaves each byte of the mapped area unallocated if it 

27266 was unallocated prior to the mapping or allocated if it was allocated prior to the mapping. The 

27267 appropriate privilege to specify the POSIX_TYPED_MEM_MAP_ALLOCATABLE flag is 

27268 implementation-dependent. 

27269 If successful, posix_typed_mem_open () returns a file descriptor for the typed memory object that 

27270 is the lowest numbered file descriptor not currently open for that process. The open file 

27271 description is new, and therefore the file descriptor does not share it with any other processes. It 

27272 is unspecified whether the file offset is set. The FD_CLOEXEC file descriptor flag associated 

27273 with the new file descriptor shall be cleared. 

27274 The behavior of msync(), ftruncate(), and all file operations other than mmap(), 

27275 posix_mem_offset (), posix_typed_mem_get_info(),fstat() r dup (), dup2(), and close (), is unspecified 

27276 when passed a file descriptor connected to a typed memory object by this function. 

27277 The file status flags of the open file description shall be set according to the value of oflag. 

27278 Applications shall specify exactly one of the three access mode values described below and 

27279 defined in the header <fcntl.h>, as the value of oflag. 

27280 0_RD0NLY Open for read access only. 

27281 0_WR0NLY Open for write access only. 

27282 0_RDWR Open for read or write access. 

27283 RETURN VALUE 

27284 Upon successful completion, the posix_typed_mem_open () function shall return a non-negative 

27285 integer representing the lowest numbered unused file descriptor. Otherwise, it shall return -1 

27286 and set errno to indicate the error. 


27287 ERRORS 

27288 The posix_typed_mem_open () function shall fail if: 

27289 [EACCES] The typed memory object exists and the permissions specified by oflag are 

27290 denied. 


27291 


[EINTR] 


The posix_typed_mem_open () operation was interrupted by a signal. 


27292 

27293 

27294 

27295 


[EINVAL] The flags specified in tflag are invalid (more than one of 

POSIX_TYPED_MEM_ALLOCATE, 
POSIX_TYPED_MEM_ALLOCATE_CONTIG, or 
POSIX_TYPED_MEM_MAP_ALLOCATABLE is specified). 


27296 

27297 

27298 

27299 

27300 


[EMFILE] Too many file descriptors are currently in use by this process. 

[ENAMETOOLONG] 

The length of the name string exceeds {PATH_MAX}, or a path name 
component is longer than |NAME_MAX} while j_POSIX_NO_TRUNC} is in 
effect. 


27301 

27302 

27303 

27304 


[ENFILE] Too many file descriptors are currently open in the system. 

[ENOENT] The named typed memory object does not exist. 

[EPERM] The caller lacks the appropriate privilege to specify the flag 

POSIX_TYPED_MEM_MAP_ALLOC ATABLE in argument tflag. 
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27305 EXAMPLES 

27306 None. 

27307 APPLICATION USAGE 

27308 None. 

27309 RATIONALE 

27310 None. 

27311 FUTURE DIRECTIONS 

27312 None. 

27313 SEE ALSO 

27314 close(), dup (), exec, fcntl(), fstat (), ftnmcate(), mmap(), msync(), posix_mem_offset ( ), 

27315 posix_typed_mem_get_info (), itmask (), the System Interface Definitions volume of 

27316 IEEE Std. 1003.1-200x, <fcntl.h,> <sys/mman.h> 

27317 CHANGE HISTORY 

27318 First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. 
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27319 NAME 

27320 pow — power function 

27321 SYNOPSIS 

27322 #include <math.h> 

27323 double pow (double x, double y) ; 

27324 DESCRIPTION 

27325 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

27326 conflict between the requirements described here and the ISO C standard is unintentional. This I 

27327 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

27328 The pozv( ) function shall compute the value of x raised to the power y, x y . If x is negative, the I 

27329 application shall ensure that y is an integer value. I 

27330 An application wishing to check for error situations should set errno to 0 before calling pozv( ). If 

27331 errno is non-zero on return, or the return value is NaN, an error has occurred. 

27332 RETURN VALUE 

27333 Upon successful completion, pozv() shall return the value of x raised to the power y. 

27334 If x is 0 and y is 0,1.0 shall be returned. 

27335 xsi If y is NaN, or y is non-zero and x is NaN, NaN shall be returned and errno may be set to 

27336 [EDOM]. If y is 0.0 and x is NaN, either 1.0 shall be returned, or NaN shall be returned and errno 

27337 may be set to [EDOM]. 

27338 xsi If x is 0.0 and y is negative, -HUGE_VAL shall be returned and errno may be set to [EDOM] or 

27339 [ERANGE]. 

27340 If the correct value would cause overflow, ±HUGE_VAL shall be returned, and errno set to 

27341 [ERANGE]. 

27342 If the correct value would cause underflow, 0 is returned and errno may be set to [ERANGE]. 

27343 ERRORS 

27344 The pozv( ) function shall fail if: 

27345 [EDOM] The value of x is negative and y is non-integral. 

27346 [ERANGE] The value to be returned would have caused overflow. 

27347 The pozv () function may fail if: 

27348 xsi [EDOM] The value of x is 0.0 and y is negative, or y is NaN. 

27349 [ERANGE] The correct value would cause underflow. 

27350 xsi No other errors shall occur. 

27351 EXAMPLES 

27352 None. 

27353 APPLICATION USAGE 

27354 None. 

27355 RATIONALE 

27356 None. 
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27357 FUTURE DIRECTIONS 

27358 None. 

27359 SEE ALSO 

27360 exp( ), isnan (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

27361 CHANGE HISTORY 

27362 First released in Issue 1. 

27363 Derived from Issue 1 of the SVID. 

27364 Issue 4 

27365 References to matherr( ) are removed. 

27366 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

27367 ISO C standard and to rationalize error handling in the mathematics functions. 

27368 The return value specified for [EDOM] is marked as an extension. 

27369 Issue 5 

27370 The DESCRIPTION is updated to indicate how an application should check for an error. This 

27371 text was previously published in the APPLICATION USAGE section. 

27372 Issue 6 

27373 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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27374 NAME 

27375 pread — read from a file 

27376 SYNOPSIS 

27377 xsi #include <unistd.h> 

27378 ssize_t pread(int fildes, void *buf, size_t nbyte, off_t offset); 

27379 

27380 DESCRIPTION 

27381 Refer to read (). 
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27382 NAME 

27383 printf — print formatted output 

27384 SYNOPSIS 

27385 #include <stdio.h> 

27386 int printf (const char * format, . . . ) ; 

27387 DESCRIPTION 

27388 Refer to fprin tf( ). 
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27389 

27390 

27391 

27392 

27393 

27394 

27395 

27396 

27397 

27398 

27399 

27400 

27401 

27402 

27403 

27404 

27405 

27406 

27407 

27408 

27409 

27410 

27411 

27412 

27413 

27414 

27415 

27416 

27417 

27418 

27419 

27420 

27421 

27422 

27423 

27424 

27425 

27426 

27427 

27428 

27429 

27430 

27431 

27432 

27433 

27434 


NAME 

pthread_atfork — register fork handlers 

SYNOPSIS 

thr #include <pthread.h> 

#include <sys/types.h> 

#include <unistd.h> 

int pthread_atfork(void (* prepare )(void), void (*parent) (void), 
void {*child) (void)); 


DESCRIPTION 

The pthread_atfork() function shall declare fork handlers to be called before and after fork (), in 
the context of the thread that called fork (). The prepare fork handler shall be called before fork () 
processing commences. The parent fork handle shall be called after fork () processing completes 
in the parent process. The child fork handler shall be called after fork () processing completes in 
the child process. If no handling is desired at one or more of these three points, the 
corresponding fork handler address(es) may be set to NULL. 

The order of calls to pthread_atfork{) is significant. The parent and child fork handlers shall be 
called in the order in which they were established by calls to pthread_atfork(). The prepare fork 
handlers shall be called in the opposite order. 

RETURN VALUE 

Upon successful completion, pthread_atfork() shall return a value of zero; otherwise, an error 
number shall be returned to indicate the error. 

ERRORS 

The pthread_atfork() function shall fail if: 

[ENOMEM] Insufficient table space exists to record the fork handler addresses. 

The pthread_atfork( ) function does not return an error code of [EINTR], 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

There are at least two serious problems with the semantics of fork() in a multi-threaded 
program. One problem has to do with state (for example, memory) covered by mutexes. 
Consider the case where one thread has a mutex locked and the state covered by that mutex is 
inconsistent while another thread calls fork(). In the child, the mutex is in the locked state 
(locked by a nonexistent thread and thus can never be unlocked). Having the child simply 
reinitialize the mutex is unsatisfactory since this approach does not resolve the question about 
how to correct or otherwise deal with the inconsistent state in the child. 

It is suggested that programs that use fork () call an exec function very soon afterwards in the 
child process, thus resetting all states. In the meantime, only a short list of async-signal-safe 
library routines are promised to be available. 

Unfortunately, this solution does not address the needs of multi-threaded libraries. Application 
programs may not be aware that a multi-threaded library is in use, and they feel free to call any 
number of library routines between the fork () and exec calls, just as they always have. Indeed, 
they may be extant single-threaded programs and cannot, therefore, be expected to obey new 
restrictions imposed by the threads library. 
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27435 On the other hand, the multi-threaded library needs a way to protect its internal state during 

27436 fork () in case it is re-entered later in the child process. The problem arises especially in multi- 

27437 threaded I/O libraries, which are almost sure to be invoked between the fork ( ) and exec calls to 

27438 effect I/O redirection. The solution may require locking mutex variables during fork( ), or it may 

27439 entail simply resetting the state in the child after the fork ( ) processing completes. 

27440 The pthread_atfork() function provides multi-threaded libraries with a means to protect 

27441 themselves from innocent application programs that call fork(), and it provides multi-threaded 

27442 application programs with a standard mechanism for protecting themselves from fork( ) calls in 

27443 a library routine or the application itself. 

27444 The expected usage is that the prepare handler acquires all mutex locks and the other two fork 

27445 handlers release them. 

27446 For example, an application can supply a prepare routine that acquires the necessary mutexes the 

27447 library maintains and supply child and parent routines that release those mutexes, thus ensuring 

27448 that the child gets a consistent snapshot of the state of the library (and that no mutexes are left 

27449 stranded). Alternatively, some libraries might be able to supply just a child routine that re- 

27450 initializes the mutexes in the library and all associated states to some known value (for example, 

27451 what it was when the image was originally executed). 

27452 When fork () is called, only the calling thread is duplicated in the child process. Synchronization 

27453 variables remain in the same state in the child as they were in the parent at the time fork ( ) was 

27454 called. Thus, for example, mutex locks may be held by threads that no longer exist in the child 

27455 process, and any associated states may be inconsistent. The parent process may avoid this by 

27456 explicit code that acquires and releases locks critical to the child via pthread_atfork( ). In addition, 

27457 any critical threads need to be recreated and re-initialized to the proper state in the child (also 

27458 via pthread_atfork()). 

27459 A higher-level package may acquire locks on its own data structures before invoking lower-level 

27460 packages. Under this scenario, the order specified for fork handler calls allows a simple rule of 

27461 initialization for avoiding package deadlock: a package initializes all packages on which it 

27462 depends before it calls the pthread_atfork( ) function for itself. 

27463 FUTURE DIRECTIONS 

27464 None. 

27465 SEE ALSO 

27466 atexit( ),fork( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <sys/types.h> 

27467 CHANGE HISTORY 

27468 First released in Issue 5. 

27469 Derived from the POSIX Threads Extension, including PASC Interpretation 1003.1c #4. 

27470 Issue 6 

27471 The pthread_atfork() function is marked as part of the _POSIX_THREADS option. 

27472 The <pthread.h> header is added to the SYNOPSIS. 
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27473 NAME 

27474 pthread_attr_destroy, pthread_attr_init — destroy and initialize threads attributes object 

27475 SYNOPSIS 

27476 thr #include <pthread.h> 

27477 int pthread_attr_destroy (pthread_attr_t * attr) ; 

27478 int pthread_attr_init (pthread_attr_t * attr) ; 

27479 

27480 DESCRIPTION 

27481 The pthread_attr_destroy() function is used to destroy a thread attributes object. An 

27482 implementation may cause pthread_attr_destroy() to set attr to an implementation-dependent 

27483 invalid value. The behavior of using the attribute after it has been destroyed is undefined. 

27484 The pthread_attr_init() function initializes a thread attributes object attr with the default value 

27485 for all of the individual attributes used by a given implementation. 

27486 The resulting attributes object (possibly modified by setting individual attribute values), when 

27487 used by pthread_create( ) defines the attributes of the thread created. A single attributes object can 

27488 be used in multiple simultaneous calls to pthread_create (). 

27489 RETURN VALUE 

27490 Upon successful completion, pthread_attr_destroy( ) and pthread_attr_init( ) shall return a value of 

27491 0; otherwise, an error number shall be returned to indicate the error. 

27492 ERRORS 

27493 The pthread_attr_in.it ( ) function shall fail if: 

27494 [ENOMEM] Insufficient memory exists to initialize the thread attributes object. 

27495 These functions do not return an error code of [EINTR]. 

27496 EXAMPLES 

27497 None. 

27498 APPLICATION USAGE 

27499 None. 

27500 RATIONALE 

27501 Attributes objects are provided for threads, mutexes, and condition variables as a mechanism to 

27502 support probable future standardization in these areas without requiring that the function itself 

27503 be changed. 

27504 Attributes objects provide clean isolation of the configurable aspects of threads. For example, 

27505 "stack size" is an important attribute of a thread, but it cannot be expressed portably. When 

27506 porting a threaded program, stack sizes often need to be adjusted. The use of attributes objects 

27507 can help by allowing the changes to be isolated in a single place, rather than being spread across 

27508 every instance of thread creation. 

27509 Attributes objects can be used to set up "classes' of threads with similar attributes; for example, 

27510 "threads with large stacks and high priority" or "threads with minimal stacks". These classes 

27511 can be defined in a single place and then referenced wherever threads need to be created. 

27512 Changes to "class" decisions become straightforward, and detailed analysis of each 

27513 pthread_create( ) call is not required. 

27514 The attributes objects are defined as opaque types as an aid to extensibility. If these objects had 

27515 been specified as structures, adding new attributes would force recompilation of all multi- 

27516 threaded programs when the attributes objects are extended; this might not be possible if 

27517 different program components were supplied by different vendors. 
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Additionally, opaque attributes objects present opportunities for improving performance. 
Argument validity can be checked once when attributes are set, rather than each time a thread is 
created. Implementations often need to cache kernel objects that are expensive to create. 
Opaque attributes objects provide an efficient mechanism to detect when cached objects become 
invalid due to attribute changes. 

Because assignment is not necessarily defined on a given opaque type, implementation- 
dependent default values cannot be defined in a portable way. The solution to this problem is to 
allow attributes objects to be initialized dynamically by attributes object initialization functions, 
so that default values can be supplied automatically by the implementation. 

The following proposal was provided as a suggested alternative to the supplied attributes: 

1. Maintain the style of passing a parameter formed by the bitwise-inclusive OR of flags to 
the initialization routines ( pthread_create (), pthread_mutex_init{), pthread_cond_in.it {)). The 
parameter containing the flags should be an opaque type for extensibility. If no flags are 
set in the parameter, then the objects are created with default characteristics. An 
implementation may specify implementation-dependent flag values and associated 
behavior. 

2. If further specialization of mutexes and condition variables is necessary, implementations 
may specify additional procedures that operate on the pthread_mutex_t and 
pthread_cond_t objects (instead of on attributes objects). 

The difficulties with this solution are: 

1. A bitmask is not opaque if bits have to be set into bitvector attributes objects using 
explicitly-coded bitwise-inclusive OR operations. If the set of options exceeds an int, 
application programmers need to know the location of each bit. If bits are set or read by 
encapsulation (that is, get or set functions), then the bitmask is merely an implementation 
of attributes objects as currently defined and should not be exposed to the programmer. 

2. Many attributes are not Boolean or very small integral values. For example, scheduling 
policy may be placed in 3-bit or 4-bit, but priority requires 5-bit or more, thereby taking up 
at least 8-bit out of a possible 16-bit on machines with 16-bit integers. Because of this, the 
bitmask can only reasonably control whether particular attributes are set or not, and it 
cannot serve as the repository of the value itself. The value needs to be specified as a 
function parameter (which is non-extensible), or by setting a structure field (which is non¬ 
opaque), or by get and set functions (making the bitmask a redundant addition to the 
attributes objects). 

Stack size is defined as an optional attribute because the very notion of a stack is inherently 
machine-dependent. Some implementations may not be able to change the size of the stack, for 
example, and others may not need to because stack pages may be discontiguous and can be 
allocated and released on demand. 

The attribute mechanism has been designed in large measure for extensibility. Future extensions 
to the attribute mechanism or to any attributes object defined in this volume of 
IEEE Std. 1003.1-200x has to be done with care so as not to affect binary-compatibility. 

Attributes objects, even if allocated by means of dynamic allocation functions such as malloc(), 
may have their size fixed at compile time. This means, for example, a pthread_create() in an 
implementation with extensions to the pthread_attr_t cannot look beyond the area that the 
binary application assumes is valid. This suggests that implementations should maintain a size 
field in the attributes object, as well as possibly version information, if extensions in different 
directions (possibly by different vendors) are to be accommodated. 
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27564 FUTURE DIRECTIONS 

27565 None. 

27566 SEE ALSO 

27567 pthread_attr_getstackaddr (), pthread_attr_getstacksize (), pthread_attr_getdetachstate (), 

27568 pthread_create( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

27569 CHANGE HISTORY 

27570 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

27571 Issue 6 

27572 The pthread_attr_destroy() and pthread_attr_init() functions marked as part of the 

27573 _POSIX_THREADS option. 


888 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


pthread_attr_getdetachstate() 


27574 NAME 

27575 pthread_attr_getdetachstate, pthread_attr_setdetachstate — get or set detachstate attribute 

27576 SYNOPSIS 

27577 thr #include <pthread.h> 

27578 

27579 

27580 

27581 

27582 DESCRIPTION 

27583 The detachstate attribute controls whether the thread is created in a detached state. If the thread 

27584 is created detached, then use of the ID of the newly created thread by the pthread_detach() or 

27585 pthread_join () function is an error. 

27586 The pthread_attr_getdetachstate( ) and pthread_attr_setdetachstate( ) functions, respectively, get and 

27587 set the detachstate attribute in the attr object. 

27588 For pthread_attr_getdetachstate(), detachstate shall be set to either I 

27589 PTHREAD_CREATE_DETACHED or PTHREAD_CREATE JOINABLE. 

27590 For pthread_attr_setdetachstate(), the application shall set detachstate to either I 

27591 PTHREAD_CREATE_DETACHED or PTHREAD_CREATE JOINABLE. I 

27592 A value of PTF1READ_CREATE_DETACHED causes all threads created with attr to be in the 

27593 detached state, whereas using a value of PTHREAD_CREATE JOINABLE shall cause all threads 

27594 created with attr to be in the joinable state. The default value of the detachstate attribute is 

27595 PTHREAD_CREATE JOINABLE. 

27596 RETURN VALUE 

27597 Upon successful completion, pthread_attr_getdetachstate( ) and pthread_attr_setdetachstate( ) shall 

27598 return a value of 0; otherwise, an error number shall be returned to indicate the error. 

27599 The pthread_attr_getdetachstate( ) function stores the value of the detachstate attribute in detachstate 

27600 if successful. 

27601 ERRORS 

27602 The pthread_attr_setdetachstate( ) function shall fail if: 

27603 [EINVAL] The value of detachstate was not valid 

27604 These functions do not return an error code of [EINTR]. 

27605 EXAMPLES 

27606 None. 

27607 APPLICATION USAGE 

27608 None. 

27609 RATIONALE 

27610 None. 

27611 FUTURE DIRECTIONS 

27612 None. 

27613 SEE ALSO 

27614 pthread_attr_destroy( ), pthread_attr_getstackaddr( ), pthread_attr_getstacksize( ), pthread_create( ), the 

27615 System Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 


int pthread_attr_getdetachstate(const pthread_attr_t *attr, 
int * detachstate) ; 

int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate ); 
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CHANGE HISTORY 

First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

Issue 6 

The pthread_attr_setdetachstate () and pthread_attr_getdetachstate () functions are marked as part of 
the _POSIX_THREADS option. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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27622 NAME 

27623 pthread_attr_getguardsize, pthread_attr_setguardsize — get or set the thread guardsize 

27624 attribute 

27625 Notes to Reviewers 

27626 This section zvith side shading zvill not appear in the final copy. - Ed. 

27627 This function or these functions are recommended to become mandatory parts of POSIX.l in the 

27628 next draft. 

27629 SYNOPSIS 

27630 xsi tinclude <pthread.h> 

27631 

27632 

27633 

27634 

27635 

27636 DESCRIPTION 

27637 The guardsize attribute controls the size of the guard area for the created thread's stack. The 

27638 guardsize attribute provides protection against overflow of the stack pointer. If a thread's stack is 

27639 created with guard protection, the implementation allocates extra memory at the overflow end 

27640 of the stack as a buffer against stack overflow of the stack pointer. If an application overflows 

27641 into this buffer an error results (possibly in a SIGSEGV signal being delivered to the thread). 

27642 The pthread_attr_getguardsize{) function gets the guardsize attribute in the attr object. This 

27643 attribute is returned in the guardsize parameter. 

27644 The pthread_attr_setguardsize( ) function sets the guardsize attribute in the attr object. The new 

27645 value of this attribute is obtained from the guardsize parameter. If guardsize is zero, a guard area 

27646 shall not be provided for threads created with attr. If guardsize is greater than zero, a guard area 

27647 of at least size guardsize bytes is provided for each thread created with attr. 

27648 A conforming implementation is permitted to round up the value contained in guardsize to a 

27649 multiple of the configurable system variable jPAGESIZE} (see <sys/mman.h>). If an 

27650 implementation rounds up the value of guardsize to a multiple of jPAGESIZE}, a call to 

27651 pthread_attr_getguardsize{ ) specifying attr shall store in the guardsize parameter the guard size 

27652 specified by the previous pthread_attr_setguardsize{ ) function call. 

27653 The default value of the guardsize attribute is jPAGESIZE} bytes. The actual value of jPAGESIZE} 

27654 is implementation-dependent and may not be the same on all implementations. 

27655 If the stackaddr attribute has been set (that is, the caller is allocating and managing its own thread 

27656 stacks), the guardsize attribute is ignored and no protection shall be provided by the 

27657 implementation. It is the responsibility of the application to manage stack overflow along with 

27658 stack allocation and management in this case. 

27659 RETURN VALUE 

27660 If successful, the pthread_attr_getguardsize( ) and pthread_attr_setguardsize{ ) functions shall return 

27661 zero; otherwise, an error number shall be returned to indicate the error. 

27662 ERRORS 

27663 The pthread_attr_getguardsize{ ) and pthread_attr_setguardsize( ) functions shall fail if: 

27664 [EINVAL] The attribute attr is invalid. 


int pthread_attr_getguardsize(const pthread_attr_t *attr, 
size_t *guardsize) ; 

int pthread_attr_setguardsize(pthread_attr_t *attr, 
size_t guardsize) ; 
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27665 [EINVAL] The parameter guardsize is invalid. 

27666 These functions do not return an error code of [EINTR]. 

27667 EXAMPLES 

27668 None. 

27669 APPLICATION USAGE 

27670 None. 

27671 RATIONALE 

27672 The guardsize attribute is provided to the application for two reasons: 

27673 1. Overflow protection can potentially result in wasted system resources. An application 

27674 that creates a large number of threads, and which knows its threads never overflow their 

27675 stack, can save system resources by turning off guard areas. 

27676 2. When threads allocate large data structures on the stack, large guard areas may be needed 

27677 to detect stack overflow. 

27678 FUTURE DIRECTIONS 

27679 None. 

27680 SEE ALSO 

27681 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h>, <sys/mman.h> 

27682 CHANGE HISTORY 

27683 First released in Issue 5. 

27684 Issue 6 

27685 In the ERRORS section, a third [EINVAL] error condition is removed as it is covered by the 

27686 second error condition. 
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27687 NAME 

27688 pthread_attr_getinheritsched, pthread_attr_setinheritsched — get and set inheritsched attribute 

27689 (REALTIME THREADS) 

27690 SYNOPSIS 

27691 TPS #include <pthread.h> 

27692 

27693 

27694 

27695 

27696 

27697 DESCRIPTION 

27698 The pthread_attr_getinheritsched(), and pthread_attr_setinheritsched () functions, respectively, get 

27699 and set the inheritsched attribute in the attr argument. 

27700 When the attributes objects are used by pthread_create(), the inheritsched attribute determines 

27701 how the other scheduling attributes of the created thread shall be set: I 

27702 PTHREAD_INHERIT_SCHED 

27703 Specifies that the scheduling policy and associated attributes shall be inherited from the I 

27704 creating thread, and the scheduling attributes in this attr argument shall be ignored. I 

27705 PTHREAD_EXPLICIT_SCHED 

27706 Specifies that the scheduling policy and associated attributes shall be set to the I 

27707 corresponding values from this attributes object. 

27708 The symbols PTHREAD_INHERIT_SCHED and PTHREAD_EXPLICIT_SCHED are defined in 

27709 the header <pthread.h>. 

27710 RETURN VALUE 

27711 If successful, the pthread_attr_getinheritsched () and pthread_attr_setinheritsched () functions shall 

27712 return zero; otherwise, an error number shall be returned to indicate the error. 

27713 ERRORS 

27714 The pthread_attr_setinheritsched( ) function may fail if: 

27715 [EINVAL] The value of inheritsched is not valid. 

27716 [ENOTSUP] An attempt was made to set the attribute to an unsupported value. 

27717 These functions do not return an error code of [EINTR]. 

27718 EXAMPLES 

27719 None. 

27720 APPLICATION USAGE 

27721 After these attributes have been set, a thread can be created with the specified attributes using 

27722 pthread_create( ). Using these routines does not affect the current running thread. 

27723 RATIONALE 

27724 None. 

27725 FUTURE DIRECTIONS 

27726 None. 


int pthread_attr_getinheritsched(const pthread_attr_t *attr, 
int * inheritsched) ; 

int pthread_attr_setinheritsched(pthread_attr_t *attr, 
int inheritsched) ; 
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27727 SEE ALSO 

27728 pthread_attr_destroy (), pthread_attr_getscope{ ), pthread_attr_getschedpolicy( ), 

27729 pthread_attr_getschedparam() / pthread_create( ), the System Interface Definitions volume of 

27730 IEEE Std. 1003.1-200x, <pthread.h>, <sched.h> 

27731 CHANGE HISTORY 

27732 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

27733 Marked as part of the Realtime Threads Feature Group. 

27734 Issue 6 

27735 The pthread_attr_getinheritsched() and pthread_attr_setinheritsched () functions are marked as part 

27736 of the _POSIX_THREAD_PRIORITY_SCHEDULING option. 

27737 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

27738 implementation does not support the _POSIX_THREAD_PRIORITY_SCHEDULING option. 
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27739 NAME 

27740 pthread_attr_getschedparam, pthread_attr_setschedparam — get and set schedparam attribute 

27741 SYNOPSIS 

27742 thr #include <pthread.h> 

27743 

27744 

27745 

27746 

27747 

27748 DESCRIPTION 

27749 The pthread_attr_getschedparam(), and pthread_attr_setschedparam() functions, respectively, get 

27750 and set the scheduling parameter attributes in the attr argument. The contents of the param 

27751 structure are defined in <sched.h>. For the SCHED_FIFO and SCFIED_RR policies, the only 

27752 required member of param is schedapriority . 

27753 tsp For the SCHED_SPORADIC policy, the required members of the param structure are 

27754 schedjpriority, sched_ss_low_priority , sched_ss_repl_period, sched_ss_init_budget , and 

27755 sched_ss_max_repl . The specified sched_ss_repl_period must be greater than or equal to the 

27756 specified sched_ss_init_bndget for the function to succeed; if it is not, then the function shall fail. 

27757 The value of sched_ss_max_repl shall be within the inclusive range [1,{SS_REPL_MAX}] for the 

27758 function to succeed; if not, the function shall fail. 

27759 RETURN VALUE 

27760 If successful, the pthread_attr_getschedparam() and pthread_attr_setschedparam() functions shall 

27761 return zero; otherwise, an error number shall be returned to indicate the error. 

27762 ERRORS 

27763 The pthread_attr_setschedparam( ) function may fail if: 

27764 [EINVAL] The value of param is not valid. 

27765 [ENOTSUP] An attempt was made to set the attribute to an unsupported value. 

27766 These functions do not return an error code of [EINTR]. 

27767 EXAMPLES 

27768 None. 

27769 APPLICATION USAGE 

27770 After these attributes have been set, a thread can be created with the specified attributes using 

27771 pthread_create( ). Using these routines does not affect the current running thread. 

27772 RATIONALE 

27773 None. 

27774 FUTURE DIRECTIONS 

27775 None. 

27776 SEE ALSO 

27777 pthread_attr_destroy( ), pthread_attr_getscope (), pthread_attr_getinheritsched( ), 

27778 pthread_attr_getschedpolicy( ), pthread_create( ), the System Interface Definitions volume of 

27779 IEEE Std. 1003.1-200x, <pthread.h>, <sched.h> 


int pthread_attr_getschedparam(const pthread_attr_t *attr, 
struct sched_param *param ); 
int pthread_attr_setschedparam(pthread_attr_t *attr, 
const struct sched_param *param ); 
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27780 CHANGE HISTORY 

27781 First released in Issue 5. Included for alignment with the POSIX Threads Extension. I 

27782 Issue 6 

27783 The pthread_attr_getscliedparam() and pthread_attr_setschedparam() functions are marked as part 

27784 of the _POSIX_THREADS option. I 

27785 The SCHED_SPORADIC scheduling policy is added for alignment with IEEE Std. 1003.1d-1999. I 
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27786 NAME 

27787 pthread_attr_getschedpolicy, pthread_attr_setschedpolicy — get and set schedpolicy attribute 

27788 (REALTIME THREADS) 

27789 SYNOPSIS 

27790 tps #include <pthread.h> 

27791 

27792 

27793 

27794 

27795 DESCRIPTION 

27796 The pthread_attr_getschedpolicy( ) and pthread_attr_setschedpolicy( ) functions, respectively, get and 

27797 set the schedpolicy attribute in the attr argument. 

27798 The supported values of policy shall include SCHED_FIFO, SCHED_RR, and SCHED_OTHER, 

27799 which are defined by the header <sched.h>. When threads executing with the scheduling policy I 

27800 tsp SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC are waiting on a mutex, they acquire the I 

27801 mutex in priority order when the mutex is unlocked. I 

27802 RETURN VALUE 

27803 If successful, the pthread_attr_getschedpolicy{) and pthread_attr_setschedpolicy() functions shall 

27804 return zero; otherwise, an error number shall be returned to indicate the error. 

27805 ERRORS 

27806 The pthread_attr_setschedpolicy( ) function may fail if: 

27807 [EINVAL] The value of policy is not valid. 

27808 [ENOTSUP] An attempt was made to set the attribute to an unsupported value. 

27809 These functions do not return an error code of [EINTR]. 

27810 EXAMPLES 

27811 None. 

27812 APPLICATION USAGE 

27813 After these attributes have been set, a thread can be created with the specified attributes using 

27814 pthread_create( ). Using these routines does not affect the current running thread. 

27815 RATIONALE 

27816 None. 

27817 FUTURE DIRECTIONS 

27818 None. 

27819 SEE ALSO 

27820 pthread_attr_destroy (), pthread_attr_getscope (), pthread_attr_getinheritsched (), 

27821 pthread_attr_getschedparam() / pthread_create( ), the System Interface Definitions volume of 

27822 IEEE Std. 1003.1-200x, <pthread.h>, <sched.h> 

27823 CHANGE HISTORY 

27824 First released in Issue 5. Included for alignment with the POSIX Threads Extension. I 

27825 Marked as part of the Realtime Threads Feature Group. I 


int pthread_attr_getschedpolicy(const pthread_attr_t *attr, 
int * policy) ; 

int pthread_attr_setschedpolicy(pthread_attr_t *attr, int policy); 
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Issue 6 

The pthread_attr_getschedpolicy () and pthread_attr_setschedpolicy () functions are marked as part of 
the _POSIX_THREAD_PRIORITY_SCHEDULING option. 

The [ENOSYS] error condition has been removed as stubs need not be provided if an 
implementation does not support the _POSIX_THREAD_PRIORITY_SCHEDULING option. I 

The SCHED_SPORADIC scheduling policy is added for alignment with IEEE Std. 1003.1d-1999. I 
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27832 NAME 

27833 pthread_attr_getscope, pthread_attr_setscope — get and set contentionscope attribute 

27834 (REALTIME THREADS) 

27835 SYNOPSIS 

27836 TPS #include <pthread.h> 

27837 

27838 

27839 

27840 

27841 DESCRIPTION 

27842 The pthread_attr_getscope() and pthread_attr_setscope{) functions, respectively, are used to get 

27843 and set the contentionscope attribute in the attr object. 

27844 The contentionscope attribute may have the values PTHREAD_SCOPE_SYSTEM, signifying 

27845 system scheduling contention scope, or PTHREAD_SCOPE_PROCESS, signifying process 

27846 scheduling contention scope. The symbols PTHREAD_SCOPE_SYSTEM and 

27847 PTHREAD_SCOPE_PROCESS are defined by the header <pthread.h>. 

27848 RETURN VALUE 

27849 If successful, the pthread_attr_getscope( ) and pthread_attr_setscope( ) functions shall return zero; 

27850 otherwise, an error number shall be returned to indicate the error. 

27851 ERRORS 

27852 The pthread_attr_setscope( ) function may fail if: 

27853 [EINVAL] The value of contentionscope is not valid. 

27854 [ENOTSUP] An attempt was made to set the attribute to an unsupported value. 

27855 These functions do not return an error code of [EINTR]. 

27856 EXAMPLES 

27857 None. 

27858 APPLICATION USAGE 

27859 After these attributes have been set, a thread can be created with the specified attributes using 

27860 pthread_create( ). Using these routines does not affect the current running thread. 

27861 RATIONALE 

27862 None. 

27863 FUTURE DIRECTIONS 

27864 None. 

27865 SEE ALSO 

27866 pthread_attr_destroy( ), pthread_attr_getinheritsched( ), pthread_attr_getschedpolicy (), 

27867 pthread_attr_getschedparam(), pthread_create(), the System Interface Definitions volume of 

27868 IEEE Std. 1003.1-200x, <pthread.h>, <sched.h> 

27869 CHANGE HISTORY 

27870 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

27871 Marked as part of the Realtime Threads Feature Group. 


int pthread_attr_getscope(const pthread_attr_t *attr, 
int * contentionscope) ; 

int pthread_attr_setscope(pthread_attr_t *attr, int contentionscope ); 
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Issue 6 

The pthread_attr_getscope() and pthread_attr_setscope() functions are marked as part of the 
_POSIX_THRE AD_PRIORIT Y_SCHEDULING option. 

The [ENOSYS] error condition has been removed as stubs need not be provided if an 
implementation does not support the _POSIX_THREAD_PRIORITY_SCHEDULING option. 
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27877 NAME 

27878 pthread_attr_getstackaddr, pthread_attr_setstackaddr — get and set stackaddr attribute 

27879 SYNOPSIS 

27880 thr TSA #include <pthread.h> 

27881 

27882 

27883 

27884 

27885 DESCRIPTION 

27886 The pthread_attr_getstacknddr( ) and pthread_attr_setstackaddr( ) functions, respectively, get and set 

27887 the thread creation stackaddr attribute in the attr object. 

27888 The stackaddr attribute specifies the location of storage to be used for the created thread's stack. 

27889 The size of the storage is at least PTHREAD_STACK_MIN. 

27890 RETURN VALUE 

27891 Upon successful completion, pthread_attr_getstackaddr() and pthread_attr_setstackaddr() shall 

27892 return a value of 0; otherwise, an error number shall be returned to indicate the error. 

27893 The pthread_attr_getstackaddr() function stores the stackaddr attribute value in stackaddr if 

27894 successful. 

27895 ERRORS 

27896 No errors are defined. 

27897 These functions do not return an error code of [EINTR]. 

27898 EXAMPLES 

27899 None. 

27900 APPLICATION USAGE 

27901 None. 

27902 RATIONALE 

27903 None. 

27904 FUTURE DIRECTIONS 

27905 None. 

27906 SEE ALSO 

27907 pthread_attr_destroy (), pthread_attr_getdetachstate (), pthread_attr_getstacksize (), pthread_create (), 

27908 the System Interface Definitions volume of IEEE Std. 1003.1-200x, <limits.h>, <pthread.h> 

27909 CHANGE HISTORY 

27910 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

27911 Issue 6 

27912 The pthread_attr_getstackaddr( ) and pthread_attr_setstackaddr() functions are marked as part of 

27913 the _POSIX_THREADS and _POSIX_THREAD_ATTR_STACKADDR options. 


int pthread_attr_getstackaddr(const pthread_attr_t *attr, 
void ** stackaddr) ; 

int pthread_attr_setstackaddr(pthread_attr_t *attr, void * stackaddr); 
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27914 NAME 

27915 pthread_attr_getstacksize, pthread_attr_setstacksize — get and set stacksize attribute 

27916 SYNOPSIS 

27917 thr TSA #include <pthread.h> 

27918 int pthread_attr_getstacksize (const pthread_attr_t *attr, 

27919 size_t * stacksize) ; 

27920 int pthread_attr_setstacksize(pthread_attr_t * attr, size_t stacksize) ; 

27921 

27922 DESCRIPTION 

27923 The pthread_attr_getstacksize( ) and pthread_attr_setstacksize( ) functions, respectively, get and set 

27924 the thread creation stacksize attribute in the attr object. 

27925 The stacksize attribute defines the minimum stack size (in bytes) allocated for the created threads 

27926 stack. 

27927 RETURN VALUE 

27928 Upon successful completion, pthread_attr_getstacksize() and pthread_attr_setstacksize() shall 

27929 return a value of 0; otherwise, an error number shall be returned to indicate the error. 

27930 The pthread_attr_getstacksize() function stores the stacksize attribute value in stacksize if 

27931 successful. 

27932 ERRORS 

27933 The pthread_attr_setstacksize( ) function shall fail if: 

27934 [EINVAL] The value of stacksize is less than PTHREAD_STACK_MIN or exceeds a 

27935 system-imposed limit. 

27936 These functions do not return an error code of [EINTR]. 

27937 EXAMPLES 

27938 None. 

27939 APPLICATION USAGE 

27940 None. 

27941 RATIONALE 

27942 None. 

27943 FUTURE DIRECTIONS 

27944 None. 

27945 SEE ALSO 

27946 pthread_attr_destroy(), pthread_attr_getstackaddr(), pthread_attr_getdetachstate(), pthread_create(), 

27947 the System Interface Definitions volume of IEEE Std. 1003.1-200x, <limits.h>, <pthread.h> 

27948 CHANGE HISTORY 

27949 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

27950 Issue 6 

27951 The pthread_attr_getstacksize( ) and pthread_attr_setstacksize{ ) functions are marked as part of the 

27952 _POSIX_THREADS and _POSIX_THREAD_ATTR_STACKADDR options. 
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27953 NAME 

27954 pthread_attr_init — initialize threads attributes object 

27955 SYNOPSIS 

27956 thr #include <pthread.h> 

27957 int pthread_attr_init (pthread_attr_t *attr) ; 

27958 

27959 DESCRIPTION 

27960 Refer to pthread_attr_destroy (). 
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27961 NAME 

27962 pthread_attr_setdetachstate — set detachstate attribute 

27963 SYNOPSIS 

27964 thr #include <pthread.h> 

27965 int pthread_attr_setdetachstate(pthread_attr_t *attr, int detachstate) ; 

27966 

27967 DESCRIPTION 

27968 Refer to pthread_attr_getdetachstate (). 
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27969 NAME 

27970 pthread_attr_setguardsize — set thread guardsize attribute 

27971 SYNOPSIS 

27972 xsi tinclude <pthread.h> 

27973 int pthread_attr_setguardsize (pthread_attr_t *attr, 

27974 size_t guardsize) ; 

27975 

27976 DESCRIPTION 

27977 Refer to pthrecid_attr_getgucirdsize (). 
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27978 NAME 

27979 pthread_attr_setinheritsched — set inheritsched attribute (REALTIME THREADS) 

27980 SYNOPSIS 

27981 TPS tinclude <pthread.h> 

27982 int pthread_attr_setinheritsched (pthread_attr_t *attr, 

27983 int inheritsched) ; 

27984 

27985 DESCRIPTION 

27986 Refer to pthread_attr_getinheritsched (). 
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27987 NAME 

27988 pthread_attr_setschedparam — set schedparam attribute 

27989 SYNOPSIS 

27990 thr #include <pthread.h> 

27991 int pthread_attr_setschedparam (pthread_attr_t *attr, 

27992 const struct sched_param *param) ; 

27993 

27994 DESCRIPTION 

27995 Refer to pthread_attr_getschedparam(). 
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27996 NAME 

27997 pthread_attr_setschedpolicy — set schedpolicy attribute (REALTIME THREADS) 

27998 SYNOPSIS 

27999 TPS tinclude <pthread.h> 

28000 int pthread_attr_setschedpolicy (pthread_attr_t *attr, int policy); 

28001 

28002 DESCRIPTION 

28003 Refer to pthread_attr_getschedpolicy (). 
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28004 NAME 

28005 pthread_attr_setscope — set contentionscope attribute (REALTIME THREADS) 

28006 SYNOPSIS 

28007 TPS #include <pthread.h> 

28008 int pthread_attr_setscope(pthread_attr_t *attr, int contentionscope ); 

28009 

28010 DESCRIPTION 

28011 Refer to pthread_attr_getscope (). 
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28012 NAME 

28013 pthread_attr_setstackaddr — set stackaddr attribute 

28014 SYNOPSIS 

28015 thr TSA #include <pthread.h> 

28016 int pthread_attr_setstackaddr(pthread_attr_t *attr, void *stackaddr); 

28017 

28018 DESCRIPTION 

28019 Refer to pthread_attr_getstackaddr (). 
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28020 NAME 

28021 pthread_attr_setstacksize — set stacksize attribute 

28022 SYNOPSIS 

28023 thr TSA #include <pthread.h> 

28024 int pthread_attr_setstacksize (pthread_attr_t *attr, size. 

28025 

28026 DESCRIPTION 

28027 Refer to pthread_attr_getstacksize (). 


stacksize ); 
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28028 

28029 

28030 

28031 

28032 

28033 

28034 

28035 

28036 

28037 

28038 

28039 

28040 

28041 

28042 

28043 

28044 

28045 

28046 

28047 

28048 

28049 

28050 

28051 

28052 

28053 

28054 

28055 

28056 

28057 

28058 

28059 

28060 
28061 
28062 

28063 

28064 

28065 

28066 

28067 

28068 

28069 

28070 

28071 


NAME 

pth rea d_ba rrier_destroy, pthread_barrier_init — destroy and initialize a barrier object 

Notes to Reviewers 

This section zvith side shading will not appear in the final copy. - Ed. 

The pthread_barrier_init() [EBUSY] error condition could be generalized to apply to any already 
initialized barrier. DESCRIPTION text does this. pthread_rwlock_init() [EBUSY] does this in 
Austin Draft 2 (and Draft 3). May be appropriate to file IR against 1003.1j. 

SYNOPSIS 

bar #include <pthread.h> 

int pthread_barrier_destroy(pthread_barrier_t * barrier ); 
int pthread_barrier_init(pthread_barrier_t * barrier, 

const pthread__barrierattr_t *attr, unsigned int count)} 

DESCRIPTION 

The pthread_barrier_destroy() function destroys the barrier referenced by barrier and releases any 
resources used by the barrier. The effect of subsequent use of the barrier is undefined until the 
barrier is reinitialized by another call to pthread_barrier_init (). An implementation may use this 
function to set barrier to an invalid value. The results are undefined if pthread_barrier_destroy( ) is 
called when any thread is blocked on the barrier, or if this function is called with an uninitialized 
barrier. 

The pthread_barrier_init() function shall allocate any resources required to use the barrier 
referenced by barrier and initializes the barrier with attributes referenced by attr. If attr is NULL, 
the default barrier attributes are used; the effect is the same as passing the address of a default 
barrier attributes object. The results are undefined if pthread_barrier_init() is called when any 
thread is blocked on the barrier (that is, has not returned from the pthread_barrier_zvait() call). 
The results are undefined if a barrier is used without first being initialized. The results are 
undefined if pthread_barrier_init( ) is called specifying an already initialized barrier. 

The count argument specifies the number of threads that must call pthread_barrier_zvait() before 
any of them successfully return from the call. The value specified by count must be greater than 
zero. 

If the pthread_barrier_init( ) function fails, the barrier is not initialized and the contents of barrier 
are undefined. 

Only the object referenced by barrier may be used for performing synchronization. The result of 
referring to copies of that object in calls to pthread_barrier_destroy() or pthread_barrier_zvait() is 
undefined. 

RETURN VALUE 

Upon successful completion, these functions shall return zero; otherwise, an error number shall 
be returned to indicate the error. 

ERRORS 

The pthread_barrier_destroy( ) function may fail if: 

[EBUSY] The implementation has detected an attempt to destroy a barrier while it is in 

use (for example, while being used in a pthread_barrier_wait( ) call) by another 
thread. 

[EINVAL] The value specified by barrier is invalid. 
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28072 The pthread_barrier_init( ) function shall fail if: 

28073 [EAGAIN] The system lacks the necessary resources to initialize another barrier. 

28074 [EINVAL] The value specified by count is equal to zero. 

28075 [ENOMEM] Insufficient memory exists to initialize the barrier. 

28076 The pthread_barrier_init( ) function may fail if: 

28077 [EBUSY] The implementation has detected an attempt to reinitialize a barrier while it is 

28078 in use (for example, while being used in a pthread_barrier_zvait() call) by 

28079 another thread. 

28080 [EINVAL] The value specified by attr is invalid. 

28081 These functions do not return an error code of [EINTR]. 

28082 EXAMPLES 

28083 None. 

28084 APPLICATION USAGE 

28085 The pthread_barrier_destroy() and pthread_barrier_init() functions are part of the 

28086 _POSIX_BARRIERS option and need not be provided on all implementations. 

28087 RATIONALE 

28088 None. 

28089 FUTURE DIRECTIONS 

28090 None. 

28091 SEE ALSO 

28092 pthread_barrier_zvait(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

28093 <pthread.h> 

28094 CHANGE HISTORY 

28095 First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. 

28096 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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28097 NAME 

28098 pthrcad ba rricr i ni t — initialize a barrier object 

28099 SYNOPSIS 

28100 bar #include <pthread.h> 

28101 int pthread_barrier_init (pthread_barrier_t * barrier, 

28102 const pthread_barrierattr_t *attr, unsigned int count); 

28103 

28104 DESCRIPTION 

28105 Refer to pthread_barrier_destroy (). 
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28106 

28107 

28108 

28109 

28110 
28111 

28112 

28113 

28114 

28115 

28116 

28117 

28118 

28119 

28120 
28121 

28122 

28123 

28124 

28125 

28126 

28127 

28128 

28129 

28130 

28131 

28132 

28133 

28134 

28135 

28136 

28137 

28138 

28139 

28140 

28141 

28142 

28143 

28144 

28145 

28146 

28147 


NAME 

p th rea d_ba r ri er_wa i t — synchronize at a barrier 

SYNOPSIS 

bar #include <pthread.h> 

int pthread_barrier_wait(pthread_barrier_t * barrier ); 

DESCRIPTION 

The pthread_barrier_ivait() function synchronizes participating threads at the barrier referenced 
by barrier. The calling thread blocks (that is, does not return from the pthread_barrier_zvait( ) call) 
until the required number of threads have called pthread_barrier_zvait( ) specifying the barrier. 

When the required number of threads have called pthread_barrier_zvait() specifying the barrier, 
the constant PTHREAD_BARRIER_SERIAL_THREAD is is returned to one unspecified thread 
and zero is returned to each of the remaining threads. At this point, the barrier is reset to the 
state it had as a result of the most recent pthread_barrier_init( ) function that referenced it. 

The constant PTHREAD_BARRIER_SERIAL_THREAD is defined in <pthread.h> and its value 
is distinct from any other value returned by pthread_barrier_zvait (). 

The results are undefined if this function is called with an uninitialized barrier. 

If a signal is delivered to a thread blocked on a barrier, upon return from the signal handler the 
thread shall resume waiting at the barrier if the barrier wait has not completed (that is, if the 
required number of threads have not arrived at the barrier during the execution of the signal 
handler); otherwise, the thread shall continue as normal from the completed barrier wait. Until 
the thread in the signal handler returns from it, it is unspecified whether other threads may 
proceed past the barrier once they have all reached it. 

A thread that has blocked on a barrier shall not prevent any unblocked thread that is eligible to 
use the same processing resources from eventually making forward progress in its execution. 
Eligibility for processing resources shall be determined by the scheduling policy. 

RETURN VALUE 

Upon successful completion, the pthread_barrier_zvait() function shall return 
PTHREAD_BARRIER_SERIAL_THREAD for a single (arbitrary) thread synchronized at the 
barrier and zero for each of the other threads. Otherwise, an error number shall be returned to 
indicate the error. 

ERRORS 

The pthread_barrier_zvait( ) function may fail if: 

[EINVAL] The value specified by barrier does not refer to an initialized barrier object. 

This function does not return an error code of [EINTR], 

EXAMPLES 

None. 

APPLICATION USAGE 

Applications using this function may be subject to priority inversion, as discussed in the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.290, Priority Inversion. 

The pthread_barrier_zvait() function is part of the _POSIX_BARRIERS option and need not be 
provided on all implementations. 
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28148 RATIONALE 

28149 None. 

28150 FUTURE DIRECTIONS 

28151 None. 

28152 SEE ALSO 

28153 pthread_barrier_destroy(), pthread_barrier_in.it (), the System Interface Definitions volume of 

28154 IEEE Std. 1003.1-200x, <pthread.h> 

28155 CHANGE HISTORY 

28156 First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. 

28157 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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28158 NAME 

28159 pthread_barrierattr_destroy, pthread_barrierattr_init — destroy and initialize barrier attributes 

28160 object 

28161 SYNOPSIS 

28162 bar #include <pthread.h> 

28163 int pthread_barrierattr_destroy(pthread_barrierattr_t *attr) ; 

28164 int pthread_barrierattr_init (pthread_barrierattr_t * attr) ; 

28165 

28166 DESCRIPTION 

28167 The pthread_barrierattr_destroy() function destroys a barrier attributes object. The effect of 

28168 subsequent use of the object is undefined until the object is reinitialized by another call to 

28169 pthread_barrierattr_init(). An implementation may cause pthread_barrierattr_destroy() to set the 

28170 object referenced by attr to an invalid value. 

28171 The pthread_barrierattr_init() function initializes a barrier attributes object attr with the default 

28172 value for all of the attributes defined by the implementation. 

28173 The results are undefined if pthread_barrierattr_init() is called specifying an already initialized 

28174 barrier attributes object. 

28175 After a barrier attributes object has been used to initialize one or more barriers, any function 

28176 affecting the attributes object (including destruction) does not affect any previously initialized 

28177 barrier. 

28178 RETURN VALUE 

28179 If successful, the pthread_barrierattr_destroy( ) and pthread_barrierattr_init( ) functions shall return 

28180 zero; otherwise, an error number shall be returned to indicate the error. 

28181 ERRORS 

28182 The pthread_barrierattr_destroy() function may fail if: 

28183 [EINVAL] The value specified by attr is invalid. 

28184 The pthread_barrierattr_init( ) function shall fail if: 

28185 [ENOMEM] Insufficient memory exists to initialize the barrier attributes object. 

28186 These functions do not return an error code of [EINTR]. 

28187 EXAMPLES 

28188 None. 

28189 APPLICATION USAGE 

28190 The pthread_barrierattr_destroy() and pthread_barrierattr_init() functions are part of the 

28191 _POSIX_BARRIERS option and need not be provided on all implementations. 

28192 RATIONALE 

28193 None. 

28194 FUTURE DIRECTIONS 

28195 None. 

28196 SEE ALSO 

28197 pthread_barrierattr_getpshared(), pthread_barrierattr_setpshared(), the System Interface Definitions 

28198 volume of IEEE Std. 1003.1-200x, <pthread.h>. 
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28199 

28200 

28201 


CHANGE HISTORY 

First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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28202 NAME 

28203 pthread_barrierattr_getpshared, pthread_barrierattr_setpshared — get and set process-shared 

28204 attribute of barrier attributes object 

28205 SYNOPSIS 

28206 bar TSH #include <pthread.h> 

28207 

28208 

28209 

28210 
28211 

28212 DESCRIPTION 

28213 The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a barrier to be 

28214 operated upon by any thread that has access to the memory where the barrier is allocated. If the 

28215 process-shared attribute is PTHREAD_PROCESS_PRIVATE, the barrier shall only be operated 

28216 upon by threads created within the same process as the thread that initialized the barrier; if 

28217 threads of different processes attempt to operate on such a barrier, the behavior is undefined. 

28218 The default value of the attribute shall be PTHREAD_PROCESS_PRIVATE. Both constants 

28219 PTHREAD_PROCESS_SHARED and PTHREAD_PROCESS_PRIVATE are defined in 

28220 <pthread.h>. 

28221 The pthread_barrierattr_getpshared () function obtains the value of the process-shared attribute 

28222 from the attributes object referenced by attr. The pthread_barrierattr_setpshared( ) function is used 

28223 to set the process-shared attribute in an initialized attributes object referenced by attr. 

28224 Additional attributes, their default values, and the names of the associated functions to get and 

28225 set those attribute values are implementation-dependent. 

28226 RETURN VALUE 

28227 If successful, the pthread_barrierattr_getpshared () function shall return zero and store the value of 

28228 the process-shared attribute of attr into the object referenced by the pshared parameter. 

28229 Otherwise, an error number shall be returned to indicate the error. 

28230 If successful, the pthread_barrierattr_setpshared() function shall return zero; otherwise, an error 

28231 number shall be returned to indicate the error. 

28232 ERRORS 

28233 

28234 

28235 

28236 

28237 

28238 


These functions may fail if: 

[EINVAL] The value specified by attr is invalid. 

The pthread_barrierattr_setpshared () function may fail if: 

[EINVAL] The new value specified for the process-shared attribute is not one of the legal 

values PTHREAD_PROCESS_SHARED or PTHREAD_PROCESS_PRIVATE. 

These functions do not return an error code of [EINTR], 


int pthread_barrierattr_getpshared(const pthread_barrierattr_t *attr, 
int *pshared) ; 

int pthread_barrierattr_setpshared(pthread_barrierattr_t *attr, 
int pshared) ; 
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28239 EXAMPLES 

28240 None. 

28241 APPLICATION USAGE 

28242 The pthread_barrierattr_getpshared() and pthread_barrierattr_setpslmred() functions are part of the 

28243 _POSIX_BARRIERS option and need not be provided on all implementations. 

28244 RATIONALE 

28245 None. 

28246 FUTURE DIRECTIONS 

28247 None. 

28248 SEE ALSO 

28249 pthread_barrier_in.it ( ), pthread_barrierattr_destroy( ), pthread_barrierattr_in.it ( ), the System Interface 

28250 Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

28251 CHANGE HISTORY 

28252 First released in Issue 6. Derived from IEEE Std. 1003.1j-2000 

28253 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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28254 NAME 

28255 pthread_barrierattr_init — initialize barrier attributes object 

28256 SYNOPSIS 

28257 bar #include <pthread.h> 

28258 int pthread_barrierattr_init (pthread_barrierattr_t 

28259 

28260 DESCRIPTION 

28261 Refer to pthread_barrierattr_destroy (). 


*attr) ; 
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28262 NAME 

28263 pthread_barrierattr_setpshared — set process-shared attribute of barrier attributes object 

28264 SYNOPSIS 

28265 bar TSH #include <pthread.h> 

28266 int pthread_barrierattr_setpshared(pthread_barrierattr_t *attr, 

28267 int pshared) ; 

28268 

28269 DESCRIPTION 

28270 Refer to pthread_barrierattr_getpshared(). 
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28271 NAME 

28272 pthread_cancel — cancel execution of a thread 

28273 SYNOPSIS 

28274 thr #include <pthread.h> 

28275 int pthread_cancel (pthread_t thread) ; 

28276 

28277 DESCRIPTION 

28278 The pthread_cancel() function requests that thread be canceled. The target thread's cancelability 

28279 state and type determines when the cancelation takes effect. When the cancelation is acted on, 

28280 the cancelation cleanup handlers for thread are called. When the last cancelation cleanup handler 

28281 returns, the thread-specific data destructor functions shall be called for thread. When the last 

28282 destructor function returns, thread shall be terminated. 

28283 The cancelation processing in the target thread runs asynchronously with respect to the calling 

28284 thread returning from pthread_cancel (). 

28285 RETURN VALUE 

28286 If successful, the pthread_cancel() function shall return zero; otherwise, an error number shall be 

28287 returned to indicate the error. 

28288 ERRORS 

28289 The pthread_cancel () function may fail if: 

28290 [ESRCH] No thread could be found corresponding to that specified by the given thread 

28291 ID. 

28292 The pthread_cancel () function does not return an error code of [EINTR]. 

28293 EXAMPLES 

28294 None. 

28295 APPLICATION USAGE 

28296 None. 

28297 RATIONALE 

28298 Two alternative functions were considered to sending the cancelation notification to a thread. 

28299 One would be to define a new SIGCANCEL signal that had the cancelation semantics when 

28300 delivered; the other was to define the new pthread_cancel() function, which would trigger the 

28301 cancelation semantics. 

28302 The advantage of a new signal was that so much of the delivery criteria were identical to that 

28303 used when trying to deliver a signal that making cancelation notification a signal was seen as 

28304 consistent. Indeed, many implementations implement cancelation using a special signal. On the 

28305 other hand, there would be no signal functions that could be used with this signal except 

28306 pthread_kiU(), and the behavior of the delivered cancelation signal would be unlike any 

28307 previously existing defined signal. 

28308 The benefits of a special function include the recognition that this signal would be defined 

28309 because of the similar delivery criteria and that this is the only common behavior between a 

28310 cancelation request and a signal. In addition, the cancelation delivery mechanism does not have 

28311 to be implemented as a signal. There are also strong, if not stronger, parallels with language 

28312 exception mechanisms than with signals that are potentially obscured if the delivery mechanism 

28313 is visibly closer to signals. 

28314 In the end, it was considered that as there were so many exceptions to the use of the new signal 

28315 with existing signals functions that it would be misleading. A special function has resolved this 
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28316 problem. This function was carefully defined so that an implementation wishing to provide the 

28317 cancelation functions on top of signals could do so. The special function also means that 

28318 implementations are not obliged to implement cancelation with signals. 

28319 FUTURE DIRECTIONS 

28320 None. 

28321 SEE ALSO 

28322 pthread_exit(), pthread_cond_zvait(), pthread_cond_timedivait (), pthread_join(), 

28323 pthread_setcancelstate( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

28324 <pthread.h> 

28325 CHANGE HISTORY 

28326 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

28327 Issue 6 

28328 The pthread_cancel () function is marked as part of the _POSIX_THREADS option. 
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28329 NAME 

28330 pthread_cleanup_pop, pthread_cleanup_push — establish cancelation handlers 

28331 SYNOPSIS 

28332 thr #include <pthread.h> 

28333 

28334 

28335 

28336 DESCRIPTION 

28337 The pthread_cleannp_pop() function shall remove the routine at the top of the calling thread's 

28338 cancelation cleanup stack and optionally invoke it (if execute is non-zero). 

28339 The pthreadjcleanup_push{) function shall push the specified cancelation cleanup handler routine 

28340 onto the calling thread's cancelation cleanup stack. The cancelation cleanup handler shall be 

28341 popped from the cancelation cleanup stack and invoked with the argument arg when: 

28342 • The thread exits (that is, calls pthread_exit ()). 

28343 • The thread acts upon a cancelation request. 

28344 • The thread calls pthread_cleannp_pop( ) with a non-zero execute argument. 

28345 These functions may be implemented as macros. The application shall ensure that they appear I 

28346 as statements, and in pairs within the same lexical scope (that is, the pthreadjcleanup _push {) I 

28347 macro may be thought to expand to a token list whose first token is ' {' with 

28348 pthreadjcleanup jpop{) expanding to a token list whose last token is the corresponding ' }'). 

28349 The effect of calling longjmp() or siglongjmp() is undefined if there have been any calls to 

28350 pthreadjcleanup_push() or pthreadjcleanup_pop() made without the matching call since the jump 

28351 buffer was filled. The effect of calling longjmp() or siglongjmp() from inside a cancelation 

28352 cleanup handler is also undefined unless the jump buffer was also filled in the cancelation 

28353 cleanup handler. 

28354 RETURN VALUE 

28355 The pthreadjcleanupjpush () and pthreadjcleanupjpop () functions shall return no value. 

28356 ERRORS 

28357 No errors are defined. 

28358 These functions do not return an error code of [EINTR]. 

28359 EXAMPLES 

28360 The following is an example using thread primitives to implement a cancelable, writers-priority 

28361 readers/writers lock: 

28362 typedef struct { 

28363 pthread_mutex_t lock; 

28364 pthread_cond_t rcond, 

28365 wcond; 

28366 int lock_count; /* < 0 

28367 /* > 0 

28368 /* = 0 

28369 int waiting_writers; /* 

28370 } rwlock; 

28371 void 

28372 waiting_reader_cleanup (void *arg) 

28373 { 


. . Held by writer. */ 

. . Held by lock_count readers. */ 
. . Held by nobody. */ 

Count of waiting writers. */ 


void pthread__cleanup_pop (int execute); 

void pthread_cleanup_push(void (* routine) (void*), void *arg) ; 
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28374 

28375 

28376 

28377 

28378 

28379 

28380 

28381 

28382 

28383 

28384 

28385 

28386 

28387 

28388 

28389 

28390 

28391 

28392 

28393 

28394 

28395 

28396 

28397 

28398 

28399 

28400 

28401 

28402 

28403 

28404 

28405 

28406 

28407 

28408 

28409 

28410 

28411 

28412 

28413 

28414 

28415 

28416 

28417 

28418 

28419 

28420 

28421 

28422 


rwlock *1; 

1 = (rwlock *) arg; 
pthread_mutex_unlock(&l->lock) ; 

} 

void 

lock_for_read(rwlock *1) 

{ 

pthread_mutex_lock (&1—»lock) ; 

pthread_cleanup_push(waiting_reader_cleanup, 1); 
while ( (l-alock_count < 0) && (1—>waiting_writers != 0)) 

pthread_cond_wait (&l—»rcond, &1—>lock) ; 

1—>lock_count++; 

/* 

* Note the pthread_cleanup_pop executes 

* waiting_reader_cleanup. 

*/ 

pthread_cleanup_pop(1) ; 

} 

void 

release_read_lock(rwlock *1) 

{ 

pthread_mutex_lock (&1—>lock) ; 
if (--l-4lock_count == 0) 

pthread_cond_signal (&1—»wcond) ; 
pthread_mutex_unlock(1); 

} 

void 

waiting_writer_cleanup(void *arg) 

{ 

rwlock *1; 

1 = (rwlock *) arg; 

if ((—1—»waiting_writers == 0) && (1—>lock_count >= 0)) { 
/* 

* This only happens if we have been canceled. 

*/ 

pthread_cond_broadcast (&1—>wcond) ; 

} 

pthread_mutex_unlock (&1—»lock) ; 

} 

void 

lock_for_write(rwlock *1) 

{ 

pthread_mutex_lock (&1—»lock) ; 

1—>waiting_writers+ + ; 

pthread_cleanup_push(waiting_writer_cleanup, 1); 
while (l-4lock_count != 0) 

pthread_cond_wait (&l-4wcond, &1—>lock) ; 

1—»lock_count = —1; 

/* 
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28423 

28424 

28425 

28426 

28427 

28428 

28429 

28430 

28431 

28432 

28433 

28434 

28435 

28436 

28437 

28438 

28439 

28440 

28441 

28442 

28443 

28444 

28445 

28446 

28447 

28448 

28449 

28450 

28451 

28452 

28453 

28454 

28455 

28456 

28457 

28458 

28459 

28460 

28461 

28462 

28463 

28464 

28465 

28466 

28467 

28468 


* Note the pthread_cleanup_pop executes 

* waiting_writer_cleanup. 

*/ 

pthread_cleanup_pop(1); 


void 

release_write_lock(rwlock *1) 

{ 

pthread_mutex_lock (Si—>lock) ; 

l-alock_count = 0; 

if (1—»waiting_writers == 0) 

pthread_cond_broadcast (Sl-arcond) 

else 

pthread_cond_signal (Si—>wcond) ; 
pthread_mutex_unlock (Si—>lock) ; 

} 

/* 

* This function is called to initialize the read/write lock. 
*/ 

void 

initialize_rwlock(rwlock *1) 

{ 

pthread_mutex_init (&1—»lock, pthread_mutexattr_default); 
pthread_cond_init (&1—>wcond, pthread_condattr_default); 
pthread_cond_init (Si—>rcond, pthread_condattr_default); 
l-alock_count = 0; 
l-4waiting_writers = 0; 

} 


reader_thread() 

{ 

lock_for_read(Slock); 

pthread_cleanup_push(release_read_lock. Slock); 
/* 

* Thread has read lock. 

*/ 

pthread_cleanup_pop(1) ; 

} 

writer_thread() 

{ 

lock_for_write(Slock) ; 

pthread_cleanup_push(release_write_lock. Slock); 
/* 

* Thread has write lock. 

*/ 

pthread_cleanup_pop(1); 

} 


System Interfaces, Issue 6 


927 



pthread_cleanup_pop() 


System Interfaces 


28469 

28470 

28471 

28472 

28473 

28474 

28475 

28476 

28477 

28478 

28479 

28480 

28481 

28482 

28483 

28484 

28485 

28486 

28487 

28488 

28489 

28490 

28491 

28492 

28493 

28494 

28495 

28496 

28497 

28498 

28499 

28500 

28501 

28502 

28503 

28504 

28505 

28506 

28507 

28508 

28509 

28510 

28511 

28512 


APPLICATION USAGE 

The two routines that push and pop cancelation cleanup handlers, pthread_cleanup_push () and 
pthread_cleanup_pop(), can be thought of as left and right parentheses. They always need to be 
matched. 

RATIONALE 

The restriction that the two routines that push and pop cancelation cleanup handlers, 
pthread_cleanup_push{) and pthread_cleannp_pop(), have to appear in the same lexical scope 
allows for efficient macro or compiler implementations and efficient storage management. A 
sample implementation of these routines as macros might look like this: 

tdefine pthread_cleanup_push(rtn,arg) { \ 

struct _pthread_handler_rec _cleanup_handler, **_head; \ 

_cleanup_handler.rtn = rtn; \ 

_cleanup_handler.arg = arg; \ 

(void) pthread_getspecific(_pthread_handler_key, &_head); \ 

_cleanup_handler.next = *_head; \ 

* _head = &_cleanup_handler; 

tdefine pthread_cleanup_pop(ex) \ 

* _head = _cleanup_handler.next; \ 

if (ex) (* _cleanup_handler.rtn)(_cleanup_handler.arg); \ 

} 

A more ambitious implementation of these routines might do even better by allowing the 
compiler to note that the cancelation cleanup handler is a constant and can be expanded inline. 

This volume of IEEE Std. 1003.1-200x currently leaves unspecified the effect of calling longjmp () 
from a signal handler executing in a POSIX System Interfaces function. If an implementation 
wants to allow this and give the programmer reasonable behavior, the longjmp () function has to 
call all cancelation cleanup handlers that have been pushed but not popped since the time 
setjmp() was called. 

Consider a multi-threaded function called by a thread that uses signals. If a signal were 
delivered to a signal handler during the operation of qsort() and that handler were to call 
longjmp () (which, in turn, did not call the cancelation cleanup handlers) the helper threads 
created by the qsortj) function would not be canceled. Instead, they would continue to execute 
and write into the argument array even though the array might have been popped off of the 
stack. 

Note that the specified cleanup handling mechanism is especially tied to the C language and, 
while the requirement for a uniform mechanism for expressing cleanup is language- 
independent, the mechanism used in other languages may be quite different. In addition, this 
mechanism is really only necessary due to the lack of a real exception mechanism in the C 
language, which would be the ideal solution. 

There is no notion of a cancelation cleanup-safe function. If an application has no cancelation 
points in its signal handlers, blocks any signal whose handler may have cancelation points while 
calling async-unsafe functions, or disables cancelation while calling async-unsafe functions, all 
functions maybe safely called from cancelation cleanup routines. 

FUTURE DIRECTIONS 

None. 
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28513 

28514 

28515 

28516 

28517 

28518 

28519 

28520 

28521 

28522 


SEE ALSO 

pthread_cancel(), pthread_setcancelstate(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <pthread.h> 

CHANGE HISTORY 

First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

Issue 6 

The pthread_cleamip_pop{) and pthread_cleamip_piish() functions are marked as part of the 
_POSIX_THREADS option. 

The APPLICATION USAGE section is added. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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28523 NAME 

28524 pthread_cond_broadcast, pthread_cond_signal — broadcast or signal a condition 

28525 SYNOPSIS 

28526 thr #include <pthread.h> 

28527 int pthread_cond_broadcast (pthread_cond_t * cond) ; 

28528 int pthread_cond_signal (pthread_cond_t * cond) ; 

28529 

28530 DESCRIPTION 

28531 These functions are used to unblock threads blocked on a condition variable. 

28532 The pthread_cond_broadcast() function shall unblock all threads currently blocked on the 

28533 specified condition variable cond. 

28534 The pthread_cond_signal() function shall unblock at least one of the threads that are blocked on 

28535 the specified condition variable cond (if any threads are blocked on cond). 

28536 If more than one thread is blocked on a condition variable, the scheduling policy determines the 

28537 order in which threads are unblocked. When each thread unblocked as a result of a 

28538 pthread_cond_brondcast() or pthread_cond_signal() returns from its call to pthread_cond_wait() or 

28539 ptkread_condJimedwait( ), the thread owns the mutex with which it called pthread_cond_wait( ) or 

28540 pthreadjcondJimedwa.it ( ). The thread(s) that are unblocked shall contend for the mutex 

28541 according to the scheduling policy (if applicable), and as if each had called pthread_mntex_lock (). 

28542 The pthread_cond_broadcast() or pthread_cond_signal() functions may be called by a thread 

28543 whether or not it currently owns the mutex that threads calling pthread_cond_wait() or 

28544 pthreadjcondjtimedwait {) have associated with the condition variable during their waits; 

28545 however, if predictable scheduling behavior is required, then that mutex shall be locked by the 

28546 thread calling pthread_cond_broadcast( ) or pthread_cond_signal (). 

28547 The pthread_cond_broadcast() and pthread_cond_signal() functions have no effect if there are no 

28548 threads currently blocked on cond. 

28549 RETURN VALUE 

28550 If successful, the pthread_cond_broadcast() and pthread_cond_signal() functions shall return zero; 

28551 otherwise, an error number shall be returned to indicate the error. 

28552 ERRORS 

28553 The pthread_cond_broadcast( ) and pthread_cond_signal () function may fail if: 

28554 [EINVAL] The value cond does not refer to an initialized condition variable. 

28555 These functions do not return an error code of [EINTR]. 

28556 EXAMPLES 

28557 None. 

28558 APPLICATION USAGE 

28559 The pthread_cond_broadcast() function is used whenever the shared-variable state has been 

28560 changed in a way that more than one thread can proceed with its task. Consider a single 

28561 producer/multiple consumer problem, where the producer can insert multiple items on a list 

28562 that is accessed one item at a time by the consumers. By calling the pthread_cond_broadcast{) 

28563 function, the producer would notify all consumers that might be waiting, and thereby the 

28564 application would receive more throughput on a multiprocessor. In addition, 

28565 pthread_cond_broadcast() makes it easier to implement a readers/writer lock. The 

28566 pthread_cond_broadcast( ) function is needed in order to wake up all waiting readers when a 

28567 writer releases its lock. Finally, the two-phase commit algorithm can use this broadcast function 
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to notify all clients of an impending transaction commit. 

It is not safe to use the pthread_cond_signal () function in a signal handler that is invoked 
asynchronously. Even if it were safe, there would still be a race between the test of the Boolean 
pthread_cond_zvait( ) that could not be efficiently eliminated. 

Mutexes and condition variables are thus not suitable for releasing a waiting thread by signaling 
from code running in a signal handler. 

RATIONALE 

Multiple Awakenings by Condition Signal 

On a multiprocessor, it may be impossible for an implementation of pthread_cond_signal() to 
avoid the unblocking of more than one thread blocked on a condition variable. For example, 
consider the following partial implementation of pthread_cond_wait() and pthread_cond_signal(), 
executed by two threads in the order given. One thread is trying to wait on the condition 
variable, another is concurrently executing pthread_cond_signal(), while a third thread is already 
waiting. 

pthread_cond_wait(mutex, cond): 
value = cond—lvalue; /* 1 */ 
pthread_mutex_unlock(mutex); /* 9 */ 

pthread_mutex_lock (cond-amutex); /* 10 */ 

if (value == cond—lvalue) { /* 11 */ 
me—»next_cond = cond—^waiter; 
cond—^waiter = me; 

pthread_mutex_unlock (cond—>mutex) ; 
unable_to_run(me) ; 

} else 

pthread_mutex_unlock (cond—>mutex) ; /* 12 */ 

pthread_mutex_lock(mutex) ; /* 13 */ 

pthread_cond_signal(cond) : 

pthread_mutex_lock (cond—»mutex) ; /* 2 */ 

cond—»value + + ; /* 3 */ 
if (cond—^waiter) { /* 4 */ 

sleeper = cond—^waiter; /* 5 */ 

cond—^waiter = sleeper—»next_cond; /* 6 */ 

able_to_run(sleeper); /* 7 */ 

} 

pthread_mutex_unlock (cond—»mutex) ; /* 8 */ 

The effect is that more than one thread can return from its call to pthread_cond_wait{) or 
pthread_cond_timedwait( ) as a result of one call to pthread_cond_signal(). This effect is called 
"spurious wakeup". Note that the situation is self-correcting in that the number of threads that 
are so awakened is finite; for example, the next thread to call pthread_cond_wait () after the 
sequence of events above blocks. 

While this problem could be resolved, the loss of efficiency for a fringe condition that occurs 
only rarely is unacceptable, especially given that one has to check the predicate associated with a 
condition variable anyway. Correcting this problem would unnecessarily reduce the degree of 
concurrency in this basic building block for all higher-level synchronization operations. 

An added benefit of allowing spurious wakeups is that applications are forced to code a 
predicate-testing-loop around the condition wait. This also makes the application tolerate 
superfluous condition broadcasts or signals on the same condition variable that may be coded in 
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28615 some other part of the application. The resulting applications are thus more robust. Therefore, 

28616 IEEE Std. 1003.1-200x explicitly documents that spurious wakeups may occur. 

28617 FUTURE DIRECTIONS 

28618 None. 

28619 SEE ALSO 

28620 pthread_cond_destroy{), pthread_cond_timedwait(), pthread_cond_zvait(), the System Interface 

28621 Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

28622 CHANGE HISTORY 

28623 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

28624 Issue 6 

28625 The pthread_cond_broadcast() and pthread_cond_signal() functions are marked as part of the 

28626 _POSIX_THREADS option. 

28627 The APPLICATION USAGE section is added. 
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28628 NAME 

28629 pthread_cond_destroy, pthread_cond_init — destroy and initialize condition variables 

28630 SYNOPSIS 

28631 thr #include <pthread.h> 

28632 

28633 

28634 

28635 

28636 

28637 DESCRIPTION 

28638 The pthread_cond_destroy() function destroys the given condition variable specified by cond ; the 

28639 object becomes, in effect, uninitialized. An implementation may cause pthread_cond_destroy( ) to 

28640 set the object referenced by cond to an invalid value. A destroyed condition variable object can be 

28641 re-initialized using pthread_cond_init (); the results of otherwise referencing the object after it has 

28642 been destroyed are undefined. 

28643 It shall be safe to destroy an initialized condition variable upon which no threads are currently 

28644 blocked. Attempting to destroy a condition variable upon which other threads are currently 

28645 blocked results in undefined behavior. 

28646 The pthread_cond_init( ) function initializes the condition variable referenced by cond with 

28647 attributes referenced by attr. If attr is NULL, the default condition variable attributes are used; 

28648 the effect is the same as passing the address of a default condition variable attributes object. 

28649 Upon successful initialization, the state of the condition variable becomes initialized. 

28650 Attempting to initialize an already initialized condition variable results in undefined behavior. 

28651 In cases where default condition variable attributes are appropriate, the macro 

28652 PTHREAD_COND_INITIALIZER can be used to initialize condition variables that are statically 

28653 allocated. The effect shall be equivalent to dynamic initialization by a call to pthread_cond_init {) 

28654 with parameter attr specified as NULL, except that no error checks are performed. 

28655 RETURN VALUE 

28656 If successful, the pthread_cond_destroy() and pthread_cond_init{ ) functions shall return zero; 

28657 otherwise, an error number shall be returned to indicate the error. 

28658 The [EBUSY] and [EINVAL] error checks, if implemented, shall act as if they were performed 

28659 immediately at the beginning of processing for the function and caused an error return prior to 

28660 modifying the state of the condition variable specified by cond. 

28661 ERRORS 

28662 The pthread_cond_destroy( ) function may fail if: 

28663 [EBUSY] The implementation has detected an attempt to destroy the object referenced 

28664 by cond while it is referenced (for example, while being used in a 

28665 pthread_cond_zvait( ) or pthread_cond_timedwait( )) by another thread. 

28666 [EINVAL] The value specified by cond is invalid. 

28667 The pthread_cond_init () function shall fail if: 

28668 [EAGAIN] The system lacked the necessary resources (other than memory) to initialize 

28669 another condition variable. 

28670 [ENOMEM] Insufficient memory exists to initialize the condition variable. 


int pthread_cond_destroy(pthread_cond_t * cond ); 
int pthread_cond_init(pthread_cond_t *cond, 
const pthread_condattr_t *attr ); 
pthread_cond_t cond = PTHREAD_COND_INITIALIZER; 
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28671 The pthread_cond_init () function may fail if: 


28672 

28673 

28674 


[EBUSY] The implementation has detected an attempt to re-initialize the object 

referenced by cond, a previously initialized, but not yet destroyed, condition 
variable. 


28675 [EINVAL] The value specified by attr is invalid. 


28676 These functions do not return an error code of [EINTR]. 


28677 EXAMPLES 

28678 A condition variable can be destroyed immediately after all the threads that are blocked on it are 

28679 awakened. For example, consider the following code: 

28680 struct list { 

28681 pthread_mutex_t lm; 

28682 

28683 } 


28684 

28685 

28686 

28687 

28688 

28689 

28690 

28691 

28692 

28693 

28694 


struct elt { 
key k; 
int busy; 

pthread_cond_t notbusy; 


/* Find a list element and reserve it. */ 
struct elt * 

list_find(struct list *lp, key k) 

{ 

struct elt *ep; 


28695 

28696 

28697 

28698 

28699 

28700 

28701 

28702 


pthread_mutex_lock(&lp—aim) ; 

while ((ep = find_elt(1, k) != NULL) && ep-abusy) 
pthread_cond_wait (&ep—anotbusy, &lp—>lm) ; 
if (ep != NULL) 
ep—abusy = 1; 

pthread_mutex_unlock(&lp—aim) ; 
return(ep); 


28703 

28704 

28705 

28706 

28707 

28708 

28709 

28710 

28711 

28712 

28713 


delete_elt(struct list *lp, struct elt *ep) 

{ 

pthread_mutex_lock(&lp—aim) ; 
assert (ep—abusy); 

... remove ep from list ... 
ep—abusy = 0; /* Paranoid. */ 

(A) pthread_cond_broadcast (&ep—anotbusy) ; 
pthread_mutex_unlock(&lp—aim) ; 

(B) pthread_cond_destroy (&rp—anotbusy) ; 
free(ep); 

} 


28714 In this example, the condition variable and its list element may be freed (line B) immediately 

28715 after all threads waiting for it are awakened (line A), since the mutex and the code ensure that no 

28716 other thread can touch the element to be deleted. 
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28717 APPLICATION USAGE 

28718 None. 

28719 RATIONALE 

28720 See pthread_mutex_in.it ( ); a similar rationale applies to condition variables. 

28721 FUTURE DIRECTIONS 

28722 None. 

28723 SEE ALSO 

28724 pthread_cond_broadcast(), pthread_cond_signal(), pthread_cond_timedivait(), pthread_cond_wait{), 

28725 the System Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

28726 CHANGE HISTORY 

28727 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

28728 Issue 6 

28729 The pthread_cond_destroy () and pthread_cond_in.it ( ) functions are marked as part of the 

28730 _POSIX_THREADS option. 
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28731 NAME 

28732 pthread_cond_init — initialize condition variables 

28733 SYNOPSIS 

28734 thr #include <pthread.h> 

28735 

28736 

28737 

28738 

28739 DESCRIPTION 

28740 Refer to pthread_cond_destroy (). 


int pthread_cond_init(pthread_cond_t *cond, 
const pthread_condattr_t *attr) ; 
pthread_cond_t cond = PTHREAD_COND_INITIALIZER; 
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28741 NAME 

28742 pthread_cond_signal — signal a condition 

28743 SYNOPSIS 

28744 thr #include <pthread.h> 

28745 int pthread_cond_signal (pthread_cond_t 

28746 

28747 DESCRIPTION 

28748 Refer to pthread_cond_broadcast (). 


* cond) ; 
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28749 NAME 

28750 pthread_cond_timedwait, pthread_cond_wait — wait on a condition 

28751 SYNOPSIS 

28752 thr #include <pthread.h> 

28753 

28754 

28755 

28756 

28757 DESCRIPTION 

28758 The pthread_cond_timedzvait( ) and pthread_cond_zvait( ) functions are used to block on a condition 

28759 variable. They shall be called with mutex locked by the calling thread or undefined behavior 

28760 results. 

28761 These functions atomically release mutex and cause the calling thread to block on the condition 

28762 variable cond ; atomically here means "atomically with respect to access by another thread to the 

28763 mutex and then the condition variable". That is, if another thread is able to acquire the mutex 

28764 after the about-to-block thread has released it, then a subsequent call to pthread_cond_broadcast() 

28765 or pthread_cond_signal() in that thread shall behave as if it were issued after the about-to-block 

28766 thread has blocked. 

28767 Upon successful return, the mutex has been locked and is owned by the calling thread. 

28768 When using condition variables there is always a Boolean predicate involving shared variables 

28769 associated with each condition wait that is true if the thread should proceed. Spurious wakeups 

28770 from the pthread_cond_timedivait() or pthread_cond_wait() functions may occur. Since the return 

28771 from pthread_cond_timedivait() or pthread_cond_wait() does not imply anything about the value 

28772 of this predicate, the predicate should be re-evaluated upon such return. 

28773 The effect of using more than one mutex for concurrent pthread_cond_timedivait() or 

28774 pthread_cond_wait () operations on the same condition variable is undefined; that is, a condition 

28775 variable becomes bound to a unique mutex when a thread waits on the condition variable, and 

28776 this (dynamic) binding ends when the wait returns. 

28777 A condition wait (whether timed or not) is a cancelation point. When the cancelability enable 

28778 state of a thread is set to PTHREAD_CANCEL_DEFERRED, a side effect of acting upon a 

28779 cancelation request while in a condition wait is that the mutex is (in effect) re-acquired before 

28780 calling the first cancelation cleanup handler. The effect is as if the thread were unblocked, 

28781 allowed to execute up to the point of returning from the call to pthread_cond_timediuait () or 

28782 pthread_cond_zvait( ), but at that point notices the cancelation request and instead of returning to 

28783 the caller of pthread_cond_timedivait() or pthread_cond_iuait (), starts the thread cancelation 

28784 activities, which includes calling cancelation cleanup handlers. 

28785 A thread that has been unblocked because it has been canceled while blocked in a call to 

28786 pthread_cond_timedwait( ) or pthread_cond_zvait() shall not consume any condition signal that 

28787 may be directed concurrently at the condition variable if there are other threads blocked on the 

28788 condition variable. 

28789 The pthread_cond_timedwait( ) function is the same as pthread_cond_zvait( ) except that an error is 

28790 returned if the absolute time specified by abstime passes (that is, system time equals or exceeds 

28791 abstime) before the condition cond is signaled or broadcasted, or if the absolute time specified by 

28792 cs abstime has already been passed at the time of the call. If the Clock Selection option is supported, I 

28793 the condition variable shall have a clock attribute which specifies the clock that shall be used to I 

28794 measure the time specified by the abstime argument. When such timeouts occur, I 

28795 pthread_cond_timedzuait () shall nonetheless release and re-acquire the mutex referenced by mutex. 


int pthread_cond_timedwait(pthread_cond_t *cond, 

pthread_mutex_t *mutex, const struct timespec * abstime) ; 
int pthread_cond_wait(pthread_cond_t *cond, pthread_mutex_t *mutex ); 
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28796 The pthread_cond_timedwait( ) function is also a cancelation point. 

28797 If a signal is delivered to a thread waiting for a condition variable, upon return from the signal 

28798 handler the thread resumes waiting for the condition variable as if it was not interrupted, or it 

28799 shall return zero due to spurious wakeup. 

28800 RETURN VALUE 

28801 Except in the case of [ETIMEDOUT], all these error checks shall act as if they were performed 

28802 immediately at the beginning of processing for the function and shall cause an error return, in 

28803 effect, prior to modifying the state of the mutex specified by mutex or the condition variable 

28804 specified by con d. 

28805 Upon successful completion, a value of zero shall be returned; otherwise, an error number shall 

28806 be returned to indicate the error. 

28807 ERRORS 

28808 The pthread_cond_timedwait( ) function shall fail if: 

28809 [ETIMEDOUT] The time specified by abstime to ptkread_cond_timedwait{ ) has passed. 

28810 The pthread_cond_timedwait ( ) and pthread_cond_zvait( ) functions may fail if: 

28811 [EINVAL] The value specified by cond, mutex, or abstime is invalid. 

28812 [EINVAL] Different mutexes were supplied for concurrent pthread_cond_timedwait{ ) or 

28813 pthread_cond_zvait( ) operations on the same condition variable. 

28814 [EINVAL] The mutex was not owned by the current thread at the time of the call. 

28815 These functions do not return an error code of [EINTR]. 

28816 EXAMPLES 

28817 None. 

28818 APPLICATION USAGE 

28819 None. 

28820 RATIONALE 

28821 Condition Wait Semantics 

28822 It is important to note that when pthread_cond_wait () and pthread_cond_timedwait( ) return 

28823 without error, the associated predicate may still be false. Similarly, when 

28824 pthread_cond_timedwait() returns with the timeout error, the associated predicate may be true 

28825 due to an unavoidable race between the expiration of the timeout and the predicate state change. 

28826 Some implementations, particularly on a multiprocessor, may sometimes cause multiple threads 

28827 to wake up when the condition variable is signaled simultaneously on different processors. 

28828 In general, whenever a condition wait returns, the thread has to re-evaluate the predicate 

28829 associated with the condition wait to determine whether it can safely proceed, should wait 

28830 again, or should declare a timeout. A return from the wait does not imply that the associated 

28831 predicate is either true or false. 

28832 It is thus recommended that a condition wait be enclosed in the equivalent of a "while loop" 

28833 that checks the predicate. 
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Timed Wait Semantics 

An absolute time measure was chosen for specifying the timeout parameter for two reasons. 
First, a relative time measure can be easily implemented on top of a function that specifies 
absolute time, but there is a race condition associated with specifying an absolute timeout on top 
of a function that specifies relative timeouts. For example, assume that clock_gettime( ) returns 
the current time and cond_relative_timed_wait{ ) uses relative timeouts: 

clock_gettime(CLOCK_REALTIME, Snow) 
reltime = sleep_til_this_absolute_time -now; 
cond_relative_timed_wait(c, m, Sreltime); 

If the thread is preempted between the first statement and the last statement, the thread blocks 
for too long. Blocking, however, is irrelevant if an absolute timeout is used. An absolute timeout 
also need not be recomputed if it is used multiple times in a loop, such as that enclosing a 
condition wait. 

For cases when the system clock is advanced discontinuously by an operator, it is expected that 
implementations process any timed wait expiring at an intervening time as if that time had 
actually occurred. 

Cancelation and Condition Wait 

A condition wait, whether timed or not, is a cancelation point. That is, the functions 
pthread_cond_wait() or pthreadjcond_timedwa.it {) are points where a pending (or concurrent) 
cancelation request is noticed. The reason for this is that an indefinite wait is possible at these 
points—whatever event is being waited for, even if the program is totally correct, might never 
occur; for example, some input data being awaited might never be sent. By making condition 
wait a cancelation point, the thread can be canceled and perform its cancelation cleanup handler 
even though it may be stuck in some indefinite wait. 

A side effect of acting on a cancelation request while a thread is blocked on a condition variable 
is to re-acquire the mutex before calling any of the cancelation cleanup handlers. This is done in 
order to ensure that the cancelation cleanup handler is executed in the same state as the critical 
code that lies both before and after the call to the condition wait function. This rule is also 
required when interfacing to POSIX threads from languages, such as Ada or C++, which may 
choose to map cancelation onto a language exception; this rule ensures that each exception 
handler guarding a critical section can always safely depend upon the fact that the associated 
mutex has already been locked regardless of exactly where within the critical section the 
exception was raised. Without this rule, there would not be a uniform rule that exception 
handlers could follow regarding the lock, and so coding would become very cumbersome. 

Therefore, since some statement has to be made regarding the state of the lock when a 
cancelation is delivered during a wait, a definition has been chosen that makes application 
coding most convenient and error free. 

When acting on a cancelation request while a thread is blocked on a condition variable, the 
implementation is required to ensure that the thread does not consume any condition signals 
directed at that condition variable if there are any other threads waiting on that condition 
variable. This rule is specified in order to avoid deadlock conditions that could occur if these two 
independent requests (one acting on a thread and the other acting on the condition variable) 
were not processed independently. 
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Performance of Mutexes and Condition Variables 

Mutexes are expected to be locked only for a few instructions. This practice is almost 
automatically enforced by the desire of programmers to avoid long serial regions of execution 
(which would reduce total effective parallelism). 

When using mutexes and condition variables, one tries to ensure that the usual case is to lock the 
mutex, access shared data, and unlock the mutex. Waiting on a condition variable should be a 
relatively rare situation. For example, when implementing a readers/writers lock, code that 
acquires a read-lock typically needs only to increment the count of readers (under mutual- 
exclusion) and return. The calling thread would actually wait on the condition variable only 
when there is already an active writer. So the efficiency of a synchronization operation is 
bounded by the cost of mutex lock/unlock and not by condition wait. Note that in the usual case 
there is no context switch. 

This is not to say that the efficiency of condition waiting is unimportant. Since there needs to be 
at least one context switch per Ada rendezvous, the efficiency of waiting on a condition variable 
is important. The cost of waiting on a condition variable should be little more than the minimal 
cost for a context switch plus the time to unlock and lock the mutex. 

Features of Mutexes and Condition Variables 

It had been suggested that the mutex acquisition and release be decoupled from condition wait. 
This was rejected because it is the combined nature of the operation that, in fact, facilitates 
realtime implementations. Those implementations can atomically move a high-priority thread 
between the condition variable and the mutex in a manner that is transparent to the caller. This 
can prevent extra context switches and provide more deterministic acquisition of a mutex when 
the waiting thread is signaled. Thus, fairness and priority issues can be dealt with directly by the 
scheduling discipline. Furthermore, the current condition wait operation matches existing 
practice. 

Scheduling Behavior of Mutexes and Condition Variables 

Synchronization primitives that attempt to interfere with scheduling policy by specifying an 
ordering rule are considered undesirable. Threads waiting on mutexes and condition variables 
are selected to proceed in an order dependent upon the scheduling policy rather than in some 
fixed order (for example, FIFO or priority). Thus, the scheduling policy determines which 
thread(s) are awakened and allowed to proceed. 

Timed Condition Wait 

The pthread_cond_timedivait( ) function allows an application to give up waiting for a particular 
condition after a given amount of time. An example of its use follows: 

(void) pthread_mutex_lock(&t,mn) ; 
t.waiters++; 

clock_gettime(CLOCK_REALTIME, Sts) ; 
ts.tv_sec += 5; 
rc = 0; 

while (! mypredicate(&t) && rc == 0) 

rc = pthread_cond_timedwait(&t.cond, St.mn, Sts); 
t.waiters--; 

if (rc == 0) setmystate(&t) ; 

(void) pthread_mutex_unlock(&t,mn) ; 
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28921 By making the timeout parameter absolute, it does not need to be recomputed each time the 

28922 program checks its blocking predicate. If the timeout was relative, it would have to be 

28923 recomputed before each call. This would be especially difficult since such code would need to 

28924 take into account the possibility of extra wakeups that result from extra broadcasts or signals on 

28925 the condition variable that occur before either the predicate is true or the timeout is due. 

28926 FUTURE DIRECTIONS 

28927 None. 

28928 SEE ALSO 

28929 ptliread_cond_signal(), pthread_cond_broadcast(), the System Interface Definitions volume of 

28930 IEEE Std. 1003.1-200x, <pthread.h> 

28931 CHANGE HISTORY 

28932 First released in Issue 5. Included for alignment with the POSIX Threads Extension. I 

28933 Issue 6 

28934 The pthread_cond_timediuait( ) and pthread_cond_zvait() functions are marked as part of the 

28935 _POSrX_THREADS option. 

28936 The Open Group corrigenda item U021/9 has been applied, correcting the prototype for the 

28937 pthread_cond_zvait() function. I 

28938 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by adding semantics I 

28939 for the Clock Selection option. I 
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28940 NAME 

28941 pthread_cond_wait — wait on a condition 

28942 SYNOPSIS 

28943 thr #include <pthread.h> 

28944 int pthread_cond_wait (pthread_cond_t *, pthread_mutex_t *) ; 

28945 

28946 DESCRIPTION 

28947 Refer to pthread_cond_timedwait (). 
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28948 

28949 

28950 

28951 

28952 

28953 

28954 

28955 

28956 

28957 

28958 

28959 

28960 

28961 

28962 

28963 

28964 

28965 

28966 

28967 

28968 

28969 

28970 

28971 

28972 

28973 

28974 

28975 

28976 

28977 

28978 

28979 

28980 

28981 

28982 

28983 

28984 

28985 

28986 

28987 


NAME 

pthread_condattr_destroy, pthread_condattr_init — destroy and initialize condition variable 
attributes object 

SYNOPSIS 

thr #include <pthread.h> 

int pthread_condattr_destroy(pthread_condattr_t *attr) ; 
int pthread_condattr_init(pthread_condattr_t *attr) ; 


DESCRIPTION 

The pthread_condattr_destroy() function destroys a condition variable attributes object; the object 
becomes, in effect, uninitialized. An implementation may cause pthread_condattr_destroy( ) to set 
the object referenced by attr to an invalid value. A destroyed condition variable attributes object 
can be re-initialized using pthread_condattr_in.it ()', the results of otherwise referencing the object 
after it has been destroyed are undefined. 

The pthread_condattr_init( ) function initializes a condition variable attributes object attr with the 
default value for all of the attributes defined by the implementation. 

Attempting to initialize an already initialized condition variable attributes object results in 
undefined behavior. 

After a condition variable attributes object has been used to initialize one or more condition 
variables, any function affecting the attributes object (including destruction) does not affect any 
previously initialized condition variables. 

Additional attributes, their default values, and the names of the associated functions to get and 
set those attribute values are implementation-dependent. 

RETURN VALUE 

If successful, the pthread_condattr_destroy() and pthread_condattr_init() functions shall return 
zero; otherwise, an error number shall be returned to indicate the error. 

ERRORS 

The pthread_condattr_destroy( ) function may fail if: 

[EINVAL] The value specified by attr is invalid. 

The pthread_condattr_init( ) function shall fail if: 

[ENOMEM] Insufficient memory exists to initialize the condition variable attributes object. 
These functions do not return an error code of [EINTR], 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

See pthread_attr_init( ) and pthread_mutex_in.it (). 

A process-shared attribute has been defined for condition variables for the same reason it has been 
defined for mutexes. 
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28988 FUTURE DIRECTIONS 

28989 None. 

28990 SEE ALSO 

28991 pthread_cond_destroy(), pthread_condattr_getpshared(), pthread_create(), pthread_mutex_destroy (), 

28992 the System Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

28993 CHANGE HISTORY 

28994 First released in Issue 5. Included for alignment with the POSIX Threads Extension. I 

28995 Issue 6 

28996 The pthread_condattr_destroy() and pthread_condattr_init() functions are marked as part of the I 

28997 _POSIX_THREADS option. 
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28998 NAME 

28999 pthread_condattr_getclock, pthread_condattr_setclock — get and set the clock selection 

29000 condition variable attribute 

29001 SYNOPSIS 

29002 thr CS #include <pthread.h> 

29003 

29004 

29005 

29006 

29007 

29008 DESCRIPTION 

29009 The pthread_condattr_getclock() function obtains the value of the clock attribute from the 

29010 attributes object referenced by attr. The pthread_condattr_setclock() function is used to set the 

29011 clock attribute in an initialized attributes object referenced by attr. If pthread_condattr_setclock( ) 

29012 is called with a clock_id argument that refers to a CPU-time clock, the call shall fail. 

29013 The clock attribute is the clock ID of the clock that shall be used to measure the timeout service 

29014 of pthread_cond_timedwait( ). The default value of the clock attribute shall refer to the system 

29015 clock. 

29016 RETURN VALUE 

29017 If successful, the pthread_condattr_getclock( ) function shall return zero and store the value of the 

29018 clock attribute of attr into the object referenced by the clock_id argument. Otherwise, an error 

29019 number shall be returned to indicate the error. 

29020 If successful, the pthread_condattr_setclock() function shall return zero; otherwise, an error 

29021 number shall be returned to indicate the error. 

29022 ERRORS 

29023 These functions may fail if: 

29024 [EINVAL] The value specified by attr is invalid. 

29025 The pthread_condattr_setclock( ) function may fail if: 

29026 [EINVAL] The value specified by clock_id does not refer to a known clock, or is a CPU- 

29027 time clock. 

29028 These functions do not return an error code of [EINTR]. 

29029 EXAMPLES 

29030 None. 

29031 APPLICATION USAGE 

29032 None. 

29033 RATIONALE 

29034 None. 

29035 FUTURE DIRECTIONS 

29036 None. 

29037 SEE ALSO 

29038 pthread_cond_in.it (), pthread_cond_timedwait {), pthread_condattr_destroy (), 

29039 pthread_condattr_getpshared() on page 948,1 pthread_condattr_init( ), pthread_condattr_setpshared( ) 

29040 on page 952,1 pthread_create{ ), <REFERENCE UNDEFINED>(pthread_mutex_init,)l the System 

29041 Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 


int pthread_condattr_getclock(const pthread_condattr_t *attr, 
clockid_t *clock_id) ; 

int pthread_condattr_setclock(pthread_condattr_t *attr, 
clockid_t clock_id) ; 
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29042 

29043 

29044 


CHANGE HISTORY 

First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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29051 

29052 

29053 

29054 

29055 

29056 

29057 

29058 

29059 

29060 
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29062 

29063 

29064 

29065 

29066 

29067 

29068 

29069 

29070 

29071 

29072 

29073 

29074 

29075 

29076 

29077 

29078 

29079 

29080 

29081 


NAME 

pthread_condattr_getpshared, pthread_condattr_setpshared — get and set the process-shared 
condition variable attributes 

SYNOPSIS 

thr tsh #include <pthread.h> 

int pthread_condattr_getpshared(const pthread_condattr_t *attr, 
int * pshared ); 

int pthread_condattr_setpshared(pthread_condattr_t *attr, 
int pshared) ; 


DESCRIPTION 

The pthread_condattr_getpslmred() function obtains the value of the process-shared attribute from 
the attributes object referenced by attr. The pthread_condattr_setpslmred( ) function is used to set 
the process-shared attribute in an initialized attributes object referenced by attr. 

The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a condition 
variable to be operated upon by any thread that has access to the memory where the condition 
variable is allocated, even if the condition variable is allocated in memory that is shared by 
multiple processes. If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the 
condition variable is only operated upon by threads created within the same process as the 
thread that initialized the condition variable; if threads of differing processes attempt to operate 
on such a condition variable, the behavior is undefined. The default value of the attribute is 
PTHREAD_PROCESS_PRIVATE. 

Additional attributes, their default values, and the names of the associated functions to get and 
set those attribute values are implementation-dependent. 

RETURN VALUE 

If successful, the pthread_condattr_setpshared() function shall return zero; otherwise, an error 
number shall be returned to indicate the error. 

If successful, the pthread_condattr_getpslmred() function shall return zero and store the value of 
the process-shared attribute of attr into the object referenced by the pshared parameter. Otherwise, 
an error number shall be returned to indicate the error. 

ERRORS 

The pthread_condattr_getpshared( ) and pthread_condattr_setpshared( ) functions may fail if: 
[EINVAL] The value specified by attr is invalid. 

The pthread_condattr_setpslmred( ) function may fail if: 

[EINVAL] The new value specified for the attribute is outside the range of legal values 

for that attribute. 

These functions do not return an error code of [EINTR], 
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29082 EXAMPLES 

29083 None. 

29084 APPLICATION USAGE 

29085 None. 

29086 RATIONALE 

29087 None. 

29088 FUTURE DIRECTIONS 

29089 None. 

29090 SEE ALSO 

29091 pthread_create(), pthread_cond_destroy(), pthread_condattr_destroy(), pthread_mntex_destroy{), the 

29092 System Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

29093 CHANGE HISTORY 

29094 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

29095 Issue 6 

29096 The pthread_condattr_getpshared() and pthread_condattr_setpslmred( ) functions are marked as part 

29097 of the _POSIX_THREADS and _POSIX_THREAD_PROCESS_SHARED options. 
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29098 NAME 

29099 pthread_condattr_init — initialize condition variable attributes object 

29100 SYNOPSIS 

29101 thr #include <pthread.h> 

29102 int pthread_condattr_init (pthread_condattr_t *attr) ; 

29103 

29104 DESCRIPTION 

29105 Refer to pthread_condattr_destroy (). 
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29106 NAME 

29107 pthread_condattr_setclock — set the clock selection condition variable attribute 

29108 SYNOPSIS 

29109 thr CS #include <pthread.h> 

29110 int pthread_condattr_getclock(const pthread_condattr_t *attr, 

29111 clockid_t * clock_id) ; 

29112 

29113 DESCRIPTION 

29114 Refer to pthread_condattr_getclock (). 
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29115 NAME 

29116 pthread_condattr_setpshared — set the process-shared condition variable attributes 

29117 SYNOPSIS 

29118 thr TSH #include <pthread.h> 

29119 int pthread_condattr_setpshared (pthread_condattr_t *attr, 

29120 int pshared) ; 

29121 

29122 DESCRIPTION 

29123 Refer to pthread_condattr_getpshared(). 
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29124 NAME 

29125 pthread_create — thread creation 

29126 SYNOPSIS 

29127 thr #include <pthread.h> 

29128 int pthread_create (pthread_t * thread , const pthread_attr_t *attr, 

29129 void * (* start_routine) (void*), void *arg) ; 

29130 

29131 DESCRIPTION 

29132 The pthread_create( ) function is used to create a new thread, with attributes specified by attr, 

29133 within a process. If attr is NULL, the default attributes are used. If the attributes specified by attr 

29134 are modified later, the thread's attributes are not affected. Upon successful completion, 

29135 pthread_create( ) shall store the ID of the created thread in the location referenced by thread. 

29136 The thread is created executing start_routine with arg as its sole argument. If the startjroutine 

29137 returns, the effect shall be as if there was an implicit call to pthread_exit () using the return value 

29138 of start_routine as the exit status. Note that the thread in which main() was originally invoked 

29139 differs from this. When it returns from main (), the effect shall be as if there was an implicit call 

29140 to exit () using the return value of main () as the exit status. 

29141 The signal state of the new thread shall be initialized as follows: 

29142 • The signal mask shall be inherited from the creating thread. 

29143 • The set of signals pending for the new thread shall be empty. 

29144 If pthread_create( ) fails, no new thread is created and the contents of the location referenced by 

29145 thread are undefined. I 

29146 tct If _POSIX_THREAD_CPUTIME is defined, the new thread shall have a CPU-time clock I 

29147 accessible, and the initial value of this clock shall be set to zero. I 

29148 RETURN VALUE 

29149 If successful, the pthread_create( ) function shall return zero; otherwise, an error number shall be 

29150 returned to indicate the error. 

29151 ERRORS 

29152 The pthread_create( ) function shall fail if: 

29153 [EAGAIN] The system lacked the necessary resources to create another thread, or the 

29154 system-imposed limit on the total number of threads in a process 

29155 PTHREAD_THREADS_MAX would be exceeded. 

29156 [EINVAL] The value specified by attr is invalid. 

29157 man [EPERM] The caller does not have appropriate permission to set the required 

29158 scheduling parameters or scheduling policy. 

29159 The pthread_create( ) function does not return an error code of [EINTR], 
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29160 EXAMPLES 

29161 None. 

29162 APPLICATION USAGE 

29163 None. 

29164 RATIONALE 

29165 A suggested alternative to pthread_create( ) would be to define two separate operations: create 

29166 and start. Some applications would find such behavior more natural. Ada, in particular, 

29167 separates the "creation" of a task from its "activation". 

29168 Splitting the operation was rejected by the standard developers for many reasons: 

29169 • The number of calls required to start a thread would increase from one to two and thus place 

29170 an additional burden on applications that do not require the additional synchronization. The 

29171 second call, however, could be avoided by the additional complication of a start-up state I 

29172 attribute. 

29173 • An extra state would be introduced: "created but not started". This would require the 

29174 standard to specify the behavior of the thread operations when the target has not yet started 

29175 executing. 

29176 • For those applications that require such behavior, it is possible to simulate the two separate 

29177 steps with the facilities that are currently provided. The start_routine() can synchronize by 

29178 waiting on a condition variable that is signaled by the start operation. 

29179 An Ada implementor can choose to create the thread at either of two points in the Ada program: 

29180 when the task object is created, or when the task is activated (generally at a "begin"). If the first 

29181 approach is adopted, the start_rontine() needs to wait on a condition variable to receive the 

29182 order to begin "activation". The second approach requires no such condition variable or extra 

29183 synchronization. In either approach, a separate Ada task control block would need to be created 

29184 when the task object is created to hold rendezvous queues, and so on. 

29185 An extension of the preceding model would be to allow the state of the thread to be modified 

29186 between the create and start. This would allow the thread attributes object to be eliminated. This 

29187 has been rejected because: 

29188 • All state in the thread attributes object has to be able to be set for the thread. This would 

29189 require the definition of functions to modify thread attributes. There would be no reduction 

29190 in the number of function calls required to set up the thread. In fact, for an application that 

29191 creates all threads using identical attributes, the number of function calls required to set up 

29192 the threads would be dramatically increased. Use of a thread attributes object permits the 

29193 application to make one set of attribute setting function calls. Otherwise, the set of attribute 

29194 setting function calls needs to be made for each thread creation. 

29195 • Depending on the implementation architecture, functions to set thread state would require 

29196 kernel calls, or for other implementation reasons would not be able to be implemented as 

29197 macros, thereby increasing the cost of thread creation. 

29198 • The ability for applications to segregate threads by class would be lost. 

29199 Another suggested alternative uses a model similar to that for process creation, such as "thread 

29200 fork". The fork semantics would provide more flexibility and the "create" function can be 

29201 implemented simply by doing a thread fork followed immediately by a call to the desired "start 

29202 routine" for the thread. This alternative has these problems: 

29203 • For many implementations, the entire stack of the calling thread would need to be 

29204 duplicated, since in many architectures there is no way to determine the size of the calling 

29205 frame. 


954 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


pthread_create() 


29206 

29207 

29208 

29209 

29210 

29211 

29212 

29213 

29214 

29215 

29216 

29217 

29218 

29219 

29220 

29221 


• Efficiency is reduced since at least some part of the stack has to be copied, even though in 
most cases the thread never needs the copied context, since it merely calls the desired start 
routine. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

fork(), pthread_exit(), pthread_join{), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <pthread.h> 

CHANGE HISTORY 

First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

Issue 6 

The pthread_create () function is marked as part of the _POSIX_THREADS option. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The [EPERM] mandatory error condition is added. 

The thread CPU-time clock semantics are added for alignment with IEEE Std. 1003.1d-1999. 
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29234 

29235 

29236 

29237 

29238 

29239 

29240 

29241 

29242 

29243 

29244 

29245 

29246 

29247 

29248 

29249 

29250 

29251 

29252 

29253 

29254 

29255 

29256 

29257 

29258 

29259 

29260 

29261 

29262 


NAME 

pthread_detach — detach a thread 

SYNOPSIS 

thr #include <pthread.h> 

int pthread_detach(pthread_t thread) ; 


DESCRIPTION 

The pthread_detach() function is used to indicate to the implementation that storage for the 
thread thread can be reclaimed when that thread terminates. If thread has not terminated, 
pthread_detach() shall not cause it to terminate. The effect of multiple pthread_detach() calls on 
the same target thread is unspecified. 

RETURN VALUE 

If the call succeeds, pthread_detach() shall return 0; otherwise, an error number shall be returned 
to indicate the error. 

ERRORS 

The pthread_detach() function shall fail if: 

[EINVAL] The implementation has detected that the value specified by thread does not 

refer to a joinable thread. 

[ESRCH] No thread could be found corresponding to that specified by the given thread 

ID. 

The pthread_detach() function does not return an error code of [EINTR], 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

The pthread_join () or pthread_detach() functions should eventually be called for every thread that 
is created so that storage associated with the thread may be reclaimed. 

It has been suggested that a "detach" function is not necessary; the detachstate thread creation 
attribute is sufficient, since a thread need never be dynamically detached. However, need arises 
in at least two cases: 

1. In a cancelation handler for a pthread_join () it is nearly essential to have a pthread_detach() 
function in order to detach the thread on which pthread_join () was waiting. Without it, it 
would be necessary to have the handler do another pthread_join () to attempt to detach the 
thread, which would both delay the cancelation processing for an unbounded period and 
introduce a new call to pthread_join(), which might itself need a cancelation handler. A 
dynamic detach is nearly essential in this case. 

2. In order to detach the "initial thread" (as may be desirable in processes that set up server 
threads). 

FUTURE DIRECTIONS 

None. 
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29263 SEE ALSO 

29264 pthread_join (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

29265 CHANGE HISTORY 

29266 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

29267 Issue 6 

29268 The pthread_detach () function is marked as part of the _POSIX_THREADS option. 
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29269 NAME 

29270 pthread_equal — compare thread IDs 

29271 SYNOPSIS 

29272 thr #include <pthread.h> 

29273 int pthread_equal (pthread_t tl, pthread_t t2) ; 

29274 

29275 DESCRIPTION 

29276 This function compares the thread IDs tl and t2. 

29277 RETURN VALUE 

29278 The pthread_eqnal() function shall return a non-zero value if tl and tl are equal; otherwise, zero 

29279 shall be returned. 

29280 If either tl or tl are not valid thread IDs, the behavior is undefined. 

29281 ERRORS 

29282 No errors are defined. 

29283 The pthread_equal () function shall not return an error code of [EINTR]. 

29284 EXAMPLES 

29285 None. 

29286 APPLICATION USAGE 

29287 None. 

29288 RATIONALE 

29289 Implementations may choose to define a thread ID as a structure. This allows additional 

29290 flexibility and robustness over using an int. For example, a thread ID could include a sequence 

29291 number that allows detection of "dangling IDs" (copies of a thread ID that has been detached). 

29292 Because the C language does not support comparison on structure types, the pthread_eqnal{) 

29293 function is provided to compare thread IDs. 

29294 FUTURE DIRECTIONS 

29295 None. 

29296 SEE ALSO 

29297 pthread_create (), pthread_self( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

29298 <pthread.h> 

29299 CHANGE HISTORY 

29300 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

29301 Issue 6 

29302 The pthread_eqnal () function is marked as part of the _POSIX_THREADS option. 
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29303 NAME 

29304 pthread_exit — thread termination 

29305 SYNOPSIS 

29306 thr #include <pthread.h> 

29307 void pthread_exit (void *value_ptr) ; 

29308 

29309 DESCRIPTION 

29310 The pthread_exit () function shall terminate the calling thread and make the value valne_ptr 

29311 available to any successful join with the terminating thread. Any cancelation cleanup handlers 

29312 that have been pushed and not yet popped shall be popped in the reverse order that they were 

29313 pushed and then executed. After all cancelation cleanup handlers have been executed, if the 

29314 thread has any thread-specific data, appropriate destructor functions shall be called in an 

29315 unspecified order. Thread termination does not release any application visible process resources, 

29316 including, but not limited to, mutexes and file descriptors, nor does it perform any process-level 

29317 cleanup actions, including, but not limited to, calling any atexit{ ) routines that may exist. 

29318 An implicit call to pthread_exit () is made when a thread other than the thread in which main () 

29319 was first invoked returns from the start routine that was used to create it. The function's return 

29320 value serves as the thread's exit status. 

29321 The behavior of pthread_exit () is undefined if called from a cancelation cleanup handler or 

29322 destructor function that was invoked as a result of either an implicit or explicit call to 

29323 pthread_exit(). 

29324 After a thread has terminated, the result of access to local (auto) variables of the thread is 

29325 undefined. Thus, references to local variables of the exiting thread should not be used for the 

29326 pthread_exit () valuejptr parameter value. 

29327 The process shall exit with an exit status of 0 after the last thread has been terminated. The 

29328 behavior shall be as if the implementation called exit() with a zero argument at thread 

29329 termination time. 

29330 RETURN VALUE 

29331 The pthread_exit () function cannot return to its caller. 

29332 ERRORS 

29333 No errors are defined. 

29334 The pthread_exit () function shall not return an error code of [EINTR]. 

29335 EXAMPLES 

29336 None. 

29337 APPLICATION USAGE 

29338 None. 

29339 RATIONALE 

29340 The normal mechanism by which a thread terminates is to return from the routine that was 

29341 specified in the pthread_create() call that started it. The pthread_exit () function provides the 

29342 capability for a thread to terminate without requiring a return from the start routine of that 

29343 thread, thereby providing a function analogous to exit (). 

29344 Regardless of the method of thread termination, any cancelation cleanup handlers that have 

29345 been pushed and not yet popped are executed, and the destructors for any existing thread- 

29346 specific data are executed. This volume of IEEE Std. 1003.1-200x requires that cancelation 

29347 cleanup handlers be popped and called in order. After all cancelation cleanup handlers have 
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29348 been executed, thread-specific data destructors are called, in an unspecified order, for each item 

29349 of thread-specific data that exists in the thread. This ordering is necessary because cancelation 

29350 cleanup handlers may rely on thread-specific data. 

29351 As the meaning of the status is determined by the application (except when the thread has been 

29352 canceled, in which case it is PTHREAD_CANCELED), the implementation has no idea what an 

29353 illegal status value is, which is why no address error checking is done. 

29354 FUTURE DIRECTIONS 

29355 None. 

29356 SEE ALSO 

29357 _exit(), exit(), pthread_create(), pthread_join(), the System Interface Definitions volume of 

29358 IEEE Std. 1003.1-200x, <pthread.h> 

29359 CHANGE HISTORY 

29360 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

29361 Issue 6 

29362 The pthread_exit () function is marked as part of the _POSIX_THREADS option. 
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29363 NAME 

29364 pthread_getconcurrency, pthread_setconcurrency — get or set level of concurrency 

29365 Notes to Reviewers 

29366 This section with side shading will not appear in the final copy. - Ed. 

29367 The XSI extensions, which include the RWL extensions, are recommended to become parts of I 

29368 POSIX.l _POSIX_THREADS option in the next draft. I 

29369 SYNOPSIS 

29370 XSI #include <pthread.h> 

29371 int pthread_getconcurrency (void) ; 

29372 int pthread_setconcurrency (int new_level) ; 

29373 

29374 DESCRIPTION 

29375 Unbound threads in a process may or may not be required to be simultaneously active. By 

29376 default, the threads implementation ensures that a sufficient number of threads are active so that 

29377 the process can continue to make progress. While this conserves system resources, it may not 

29378 produce the most effective level of concurrency. 

29379 The pthread_setconcurrency( ) function allows an application to inform the threads 

29380 implementation of its desired concurrency level, newjevel. The actual level of concurrency 

29381 provided by the implementation as a result of this function call is unspecified. 

29382 If newjevel is zero, it causes the implementation to maintain the concurrency level at its 

29383 discretion as if pthread_setconcnrrency{) had never been called. 

29384 The pthread_getconcnrrency{) function shall return the value set by a previous call to the 

29385 pthread_setconcurrency() function. If the pthread_setconcurrency() function was not previously 

29386 called, this function shall return zero to indicate that the implementation is maintaining the 

29387 concurrency level. 

29388 When an application calls pthread_setconcurrency() it is informing the implementation of its 

29389 desired concurrency level. The implementation uses this as a hint, not a requirement. 

29390 If an implementation does not support multiplexing of user threads on top of several kernel 

29391 scheduled entities, the pthread_setconcnrrency{) and pthread_getconcnrrency() functions are 

29392 provided for source code compatibility but they have no effect when called. To maintain the 

29393 function semantics, the newjevel parameter is saved when pthread_setconcnrrency{) is called so 

29394 that a subsequent call to pthread_getconcnrrency{) returns the same value. 

29395 RETURN VALUE 

29396 If successful, the pthread_setconcurrency( ) function shall return zero; otherwise, an error number 

29397 shall be returned to indicate the error. 

29398 The pthread_getconcurrency( ) function shall always return the concurrency level set by a previous 

29399 call to pthread_setconcnrrency{). If the pthread_setconcnrrency () function has never been called, 

29400 pthread_getconcnrrency{) shall return zero. 

29401 ERRORS 

29402 The pthread_setconcurrency( ) function shall fail if: 

29403 [EINVAL] The value specified by newjevel is negative. 

29404 [EAGAIN] The value specific by newjevel would cause a system resource to be exceeded. 
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29405 These functions do not return an error code of [EINTR]. 

29406 EXAMPLES 

29407 None. 

29408 APPLICATION USAGE 

29409 Use of these functions changes the state of the underlying concurrency upon which the 

29410 application depends. Library developers are advised to not use the pthread_getconcurrency( ) and 

29411 pthread_setconcurrency( ) functions since their use may conflict with an applications use of these 

29412 functions. 

29413 RATIONALE 

29414 None. 

29415 FUTURE DIRECTIONS 

29416 None. 

29417 SEE ALSO 

29418 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

29419 CHANGE HISTORY 

29420 First released in Issue 5. 
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29421 NAME 

29422 pthread_getcpuclockid — access a thread CPU-time clock (REALTIME) 

29423 SYNOPSIS 

29424 TCT #include <pthread.h> 

29425 tinclude <time.h> 

29426 int pthread_getcpuclockid (pthread_t thread_id, clockid_t *clock_id) ; 

29427 

29428 DESCRIPTION 

29429 The pthrecid_getcpuclockid{) function shall return in clock_id the clock ID of the CPU-time clock of 

29430 the thread specified by thread_id, if the thread specified by thread_id exists. 

29431 RETURN VALUE 

29432 Upon successful completion, pthread_getcpudockid() shall return zero; otherwise, an error 

29433 number shall be returned to indicate the error. 

29434 ERRORS 

29435 The pthread_getcpndockid( ) function may fail if: 

29436 [ESRCH] The value specified by thread_id does not refer to an existing thread. 

29437 EXAMPLES 

29438 None. 

29439 APPLICATION USAGE 

29440 The pthread_getcpndockid() function is part of the _POSIX_THREAD_CPUTIME option and need 

29441 not be provided on all implementations. 

29442 RATIONALE 

29443 None. 

29444 FUTURE DIRECTIONS 

29445 None. 

29446 SEE ALSO 

29447 dock_getcpndockid(), dock_getres(), timer_create(), the System Interface Definitions volume of 

29448 IEEE Std. 1003.1-200x, <pthread.h>, <time.h> 

29449 CHANGE HISTORY 

29450 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 

29451 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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29452 NAME 

29453 pthreacLgetschedparam, pthread_setschedparam — dynamic thread scheduling parameters 

29454 access (REALTIME THREADS) 

29455 SYNOPSIS 

29456 TPS #include <pthread.h> 

29457 

29458 

29459 

29460 

29461 

29462 DESCRIPTION 

29463 The pthread_getschedparam() and pthread_setschedparam() functions allow the scheduling policy 

29464 and scheduling parameters of individual threads within a multi-threaded process to be retrieved 

29465 and set. For SCFIED_FIFO and SCFIED_RR / the only required member of the sched_param 

29466 structure is the priority sched_priority. For SC H E DOT HER, the affected scheduling parameters 

29467 are implementation-dependent. 

29468 The pthread_getschedparam() function shall retrieve the scheduling policy and scheduling 

29469 parameters for the thread whose thread ID is given by thread and shall store those values in 

29470 policy and param, respectively. The priority value returned from pthread_getschedparam( ) shall be 

29471 the value specified by the most recent pthread_setschedparam() or pthread_create() call affecting 

29472 the target thread, and shall not reflect any temporary adjustments to its priority as a result of any 

29473 priority inheritance or ceiling functions. The pthread_setschedparam( ) function sets the scheduling 

29474 policy and associated scheduling parameters for the thread whose thread ID is given by thread to 

29475 the policy and associated parameters provided in policy and param, respectively. 

29476 The policy parameter may have the value SC H E DOT El ER, SCFIED_FIFO, or SCHED_RR. The 

29477 scheduling parameters for the SCFIED_OTHER policy are implementation-dependent. The 

29478 SCHED_FIFO and SCHED_RR policies shall have a single scheduling parameter, priority. 

29479 tsp If _POSIX_THREAD_SPORADIC_SERVER is defined, then the policy argument may have the I 

29480 value SCHED_SPORADIC, with the exception of the pthread_setschedparam( ) function that if the I 

29481 scheduling policy was not SCHED_SPORADIC at the time of the call, it is implementation- I 

29482 dependent whether the function is supported; this means that the implementation need not I 

29483 allow the application to dynamically change the scheduling policy to SCHED_SPORADIC. The I 

29484 sporadic server scheduling policy has the associated parameters sched_ss_low_priority , I 

29485 sched_ss_repl_period, sched_ss_init_budget, sched_priority , and sched_ss_max_repl. The specified I 

29486 sched_ss_repl_period must be greater than or equal to the specified sched_ss_init_budget for the I 

29487 function to succeed; if it is not, then the function shall fail. The value of sched_ss_max_repl shall I 

29488 be within the inclusive range [1,{SS_REPL_MAX}] for the function to succeed; if not, the function I 

29489 shall fail. I 

29490 If the pthread_setschedparam( ) function fails, no scheduling parameters are changed for the target I 

29491 thread. 

29492 RETURN VALUE 

29493 If successful, the pthread_getschedparam() and pthread_setschedparam () functions shall return zero; 

29494 otherwise, an error number shall be returned to indicate the error. 

29495 ERRORS 

29496 The pthread_getschedparam( ) function may fail if: 

29497 [ESRCH] The value specified by thread does not refer to a existing thread. 


int pthread_getschedparam(pthread_t thread, int * policy, 
struct sched_param *param); 

int pthread_setschedparam(pthread_t thread, int policy, 
const struct sched_param *param); 
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29498 The pthread_setschedparam( ) function may fail if: 

29499 [EINVAL] The value specified by policy or one of the scheduling parameters associated 

29500 with the scheduling policy policy is invalid. 

29501 [ENOTSUP] An attempt was made to set the policy or scheduling parameters to an 

29502 unsupported value. I 

29503 tsp [ENOTSUP] An attempt was made to dynamically change the scheduling policy to I 

29504 SCHED_SPORADIC, and the implementation does not support this change. I 

29505 [EPERM] The caller does not have the appropriate permission to set either the 

29506 scheduling parameters or the scheduling policy of the specified thread. 

29507 [EPERM] The implementation does not allow the application to modify one of the 

29508 parameters to the value specified. 

29509 [ESRCH] The value specified by thread does not refer to a existing thread. 

29510 These functions do not return an error code of [EINTR]. 

29511 EXAMPLES 

29512 None. 

29513 APPLICATION USAGE 

29514 None. 

29515 RATIONALE 

29516 None. 

29517 FUTURE DIRECTIONS 

29518 None. 

29519 SEE ALSO 

29520 sched_getparam( ), sched_getschednler(), the System Interface Definitions volume of 

29521 IEEE Std. 1003.1-200x, <pthread.h>, <sched.h> 

29522 CHANGE HISTORY 

29523 First released in Issue 5. Included for alignment with the POSIX Threads Extension. I 

29524 Issue 6 

29525 The pthread_getschedparam() and pthread_setschedparam( ) functions are marked as part of the 

29526 _POSIX_THREAD_PRIORITY_SCHEDULING option. 

29527 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

29528 implementation does not support the _POSIX_THREAD_PRIORITY_SCHEDULING option. 

29529 The Open Group corrigenda item U026/2 has been applied correcting the prototype for the 

29530 pthread_setschedparam( ) function so that its second argument is of type int. I 

29531 The SCHED_SPORADIC scheduling policy is added for alignment with IEEE Std. 1003.1d-1999. I 
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29532 NAME 

29533 pthreacLgetspecific, pthread_setspecific — thread-specific data management 

29534 SYNOPSIS 

29535 thr #include <pthread.h> 

29536 

29537 

29538 

29539 DESCRIPTION 

29540 The pthread_getspecific( ) function shall return the value currently bound to the specified key on 

29541 behalf of the calling thread. 

29542 The pthread_setspecific( ) function shall associate a thread-specific value with a key obtained via a 

29543 previous call to pthread_key_create(). Different threads may bind different values to the same 

29544 key. These values are typically pointers to blocks of dynamically allocated memory that have 

29545 been reserved for use by the calling thread. 

29546 The effect of calling pthread_getspecific() or pthread_setspecific{) with a key value not obtained 

29547 from pthread_key_create( ) or after key has been deleted with pthread_key_delete( ) is undefined. 

29548 Both pthread_getspecific() and pthread_setspecific() may be called from a thread-specific data 

29549 destructor function. However, calling pthread_setspecific() from a destructor may result in lost 

29550 storage or infinite loops. 

29551 Both functions may be implemented as macros. 

29552 RETURN VALUE 

29553 The pthread_getspecific( ) function shall return the thread-specific data value associated with the 

29554 given key. If no thread-specific data value is associated with key, then the value NULL shall be 

29555 returned. 

29556 If successful, the pthread_setspecific( ) function shall return zero; otherwise, an error number shall 

29557 be returned to indicate the error. 

29558 ERRORS 

29559 No errors are returned from pthread_getspecific( ). 

29560 The pthread_setspecific( ) function shall fail if: 

29561 [ENOMEM] Insufficient memory exists to associate the value with the key. 

29562 The pthread_setspecific( ) function may fail if: 

29563 [EINVAL] The key value is invalid. 

29564 These functions do not return an error code of [EINTR]. 

29565 EXAMPLES 

29566 None. 

29567 APPLICATION USAGE 

29568 None. 

29569 RATIONALE 

29570 Performance and ease-of-use of pthread_getspecific() is critical for functions that rely on 

29571 maintaining state in thread-specific data. Since no errors are required to be detected by it, and 

29572 since the only error that could be detected is the use of an invalid key, the function to 

29573 pthread_getspecific () has been designed to favor speed and simplicity over error reporting. 


void *pthread_getspecific(pthread_key_t key)} 

int pthread_setspecific(pthread_key_t key, const void * value) ; 
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29574 FUTURE DIRECTIONS 

29575 None. 

29576 SEE ALSO 

29577 pthread_key_create (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

29578 <pthread.h> 

29579 CHANGE HISTORY 

29580 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

29581 Issue 6 

29582 The pthread_getspecific() and pthread_setspecific() functions are marked as part of the 

29583 _POSIX_THREADS option. 
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29584 NAME 

29585 pthread_join — wait for thread termination 

29586 SYNOPSIS 

29587 thr #include <pthread.h> 

29588 int pthread_join (pthread_t thread, void **value_ptr) ; 

29589 

29590 DESCRIPTION 

29591 The pthread_join () function shall suspend execution of the calling thread until the target thread 

29592 terminates, unless the target thread has already terminated. On return from a successful 

29593 pthread_join() call with a non-NULL valuejptr argument, the value passed to pthread_exit () by 

29594 the terminating thread shall be made available in the location referenced by value_ptr. When a 

29595 pthread_join () returns successfully, the target thread has been terminated. The results of multiple 

29596 simultaneous calls to pthread_join() specifying the same target thread are undefined. If the 

29597 thread calling pthread_join () is canceled, then the target thread shall not be detached. 

29598 It is unspecified whether a thread that has exited but remains unjoined counts against 

29599 _PTHREAD_THREADS_MAX. 

29600 RETURN VALUE 

29601 If successful, the pthread_join () function shall return zero; otherwise, an error number shall be 

29602 returned to indicate the error. 

29603 ERRORS 

29604 The pthread_join () function shall fail if: 

29605 [EINVAL] The implementation has detected that the value specified by thread does not 

29606 refer to a joinable thread. 

29607 [ESRCH] No thread could be found corresponding to that specified by the given thread 

29608 ID. 

29609 The pthread_join () function may fail if: 

29610 [EDEADLK] A deadlock was detected or the value of thread specifies the calling thread. 

29611 The pthread_join () function does not return an error code of [EINTR], 

29612 EXAMPLES 

29613 An example of thread creation and deletion follows: 

29614 typedef struct { 

29615 int *ar; 

29616 long n; 

29617 } subarray; 

29618 void * 

29619 incer (void *arg) 

29620 { 

29621 long i; 

29622 for (i = 0; i < ((subarray *)arg)-an; i++) 

29623 ((subarray * ) arg) —>ar [ i ] + + ; 

29624 } 

29625 main () 

29626 { 

29627 int ar [1000000]; 
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29628 

pthread_t thl, th2; 



29629 

subarray sbl, sb2; 



29630 

sbl.ar 

= Sar[0]; 



29631 

sbl . n 

= 500000; 



29632 

(void) 

pthread_create(&thl. 

NULL, incer, &sbl); 

29633 

sb2.ar 

= Sar[500000]; 



29634 

sb2 . n 

= 500000; 



29635 

(void) 

pthread_create(&th2. 

NULL, incer, &sb2); 

29636 

(void) 

pthread_join(thl. 

NULL); 

29637 

(void) 

pthread_join(th2. 

NULL); 


29638 } 

29639 APPLICATION USAGE 

29640 None. 

29641 RATIONALE 

29642 The pthread_join () function is a convenience that has proven useful in multi-threaded 

29643 applications. It is true that a programmer could simulate this function if it were not provided by 

29644 passing extra state as part of the argument to the start_rontine( ). The terminating thread would 

29645 set a flag to indicate termination and broadcast a condition that is part of that state; a joining 

29646 thread would wait on that condition variable. While such a technique would allow a thread to 

29647 wait on more complex conditions (for example, waiting for multiple threads to terminate), 

29648 waiting on individual thread termination is considered widely useful. Also, including the 

29649 pthread_join() function in no way precludes a programmer from coding such complex waits. 

29650 Thus, while not a primitive, including pthread_join () in this volume of IEEE Std. 1003.1-200x was 

29651 considered valuable. 

29652 The pthreadjoin () function provides a simple mechanism allowing an application to wait for a 

29653 thread to terminate. After the thread terminates, the application may then choose to clean up 

29654 resources that were used by the thread. For instance, after pthread_join() returns, any 

29655 application-provided stack storage could be reclaimed. 

29656 The pthreadjoin () or pthread_detach() function should eventually be called for every thread that 

29657 is created with the detachstate attribute set to PTHREAD_CREATEJOINABLE so that storage 

29658 associated with the thread may be reclaimed. 

29659 The interaction between pthread_join () and cancelation is well-defined for the following reasons: 

29660 • The pthreadjoin () function, like all other non-async-cancel-safe functions, can only be called 

29661 with deferred cancelability type. 

29662 • Cancelation cannot occur in the disabled cancelability state. 

29663 Thus, only the default cancelability state need be considered. As specified, either the 

29664 pthread_join () call is canceled, or it succeeds, but not both. The difference is obvious to the 

29665 application, since either a cancelation handler is run or pthread_join () returns. There are no race 

29666 conditions since pthread_join () was called in the deferred cancelability state. 

29667 FUTURE DIRECTIONS 

29668 None. 

29669 SEE ALSO 

29670 pthread_create(), ivait(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

29671 <pthread.h> 
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29672 CHANGE HISTORY 

29673 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

29674 Issue 6 

29675 The pthread_join () function is marked as part of the _POSIX_THREADS option. 
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29676 NAME 

29677 pthread_key_create — thread-specific data key creation 

29678 SYNOPSIS 

29679 thr #include <pthread.h> 

29680 int pthread_key_create(pthread_key_t *key, void (* destructor) (void*)); 

29681 


29682 DESCRIPTION 

29683 The pthread_key_create( ) function shall create a thread-specific data key visible to all threads in 

29684 the process. Key values provided by pthread_key_create() are opaque objects used to locate 

29685 thread-specific data. Although the same key value may be used by different threads, the values 

29686 bound to the key by pthread_setspecific( ) are maintained on a per-thread basis and persist for the 

29687 life of the calling thread. 

29688 Upon key creation, the value NULL shall be associated with the new key in all active threads. 

29689 Upon thread creation, the value NULL shall be associated with all defined keys in the new 

29690 thread. 

29691 An optional destructor function may be associated with each key value. At thread exit, if a key 

29692 value has a non-NULL destructor pointer, and the thread has a non-NULL value associated with 

29693 that key, the function pointed to is called with the current associated value as its sole argument. 

29694 The order of destructor calls is unspecified if more than one destructor exists for a thread when 

29695 it exits. 

29696 If, after all the destructors have been called for all non-NULL values with associated destructors, 

29697 there are still some non-NULL values with associated destructors, then the process is repeated. 

29698 If, after at least |PTHREAD_DESTRUCTOR_ITERATIONS} iterations of destructor calls for 

29699 outstanding non-NULL values, there are still some non-NULL values with associated 

29700 destructors, implementations may stop calling destructors, or they may continue calling 

29701 destructors until no non-NULL values with associated destructors exist, even though this might 

29702 result in an infinite loop. 

29703 RETURN VALUE 

29704 If successful, the pthread_key_create( ) function shall store the newly created key value at *key and 

29705 shall return zero. Otherwise, an error number shall be returned to indicate the error. 


29706 ERRORS 

29707 The pthread_key_create () function shall fail if: 


29708 

29709 

29710 


[EAGAIN] The system lacked the necessary resources to create another thread-specific 

data key, or the system-imposed limit on the total number of keys per process 
PTHREAD_KEYS_MAX has been exceeded. 


29711 [ENOMEM] Insufficient memory exists to create the key. 

29712 The pthread_key_create () function does not return an error code of [EINTR]. 
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29713 EXAMPLES 

29714 The following example demonstrates a function that initializes a thread-specific data key when 

29715 it is first called, and associates a thread-specific object with each calling thread, initializing this 

29716 object when necessary. 

29717 static pthread_key_t key; 

29718 static pthread_once_t key_once = PTHREAD_ONCE_INIT; 

29719 static void 

29720 make_key () 

29721 { 

29722 (void) pthread_key_create (&key, NULL); 

29723 } 

29724 func () 

29725 { 

29726 void *ptr; 

29727 (void) pthread_once (&key_once, make_key) ; 

29728 if ( (ptr = pthread_getspecific (key) ) == NULL) { 

29729 ptr = malloc (OBJECT_SIZE) ; 

29730 

29731 (void) pthread_setspecif ic (key, ptr); 

29732 } 

29733 

29734 } 

29735 Note that the key has to be initialized before pthread_getspecific( ) or pthread_setspecific( ) can be 

29736 used. The pthread_key_create() call could either be explicitly made in a module initialization 

29737 routine, or it can be done implicitly by the first call to a module as in this example. Any attempt 

29738 to use the key before it is initialized is a programming error, making the code below incorrect. 

29739 static pthread_key_t key; 

29740 func () 

29741 { 

29742 void *ptr; 

29743 /* KEY NOT INITIALIZED!!! THIS WON'T WORK!!! */ 

29744 if ((ptr = pthread_getspecif ic (key) ) == NULL && 

29745 pthread_setspecific (key, NULL) != 0) { 

29746 pthread_key_create (&key, NULL); 

29747 

29748 } 

29749 } 

29750 APPLICATION USAGE 

29751 None. 
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29752 

29753 

29754 

29755 

29756 

29757 

29758 

29759 

29760 

29761 

29762 

29763 

29764 

29765 

29766 

29767 

29768 

29769 

29770 

29771 

29772 

29773 

29774 

29775 

29776 

29777 

29778 

29779 

29780 

29781 

29782 

29783 

29784 

29785 

29786 

29787 

29788 

29789 

29790 

29791 

29792 

29793 

29794 


RATIONALE 

Destructor Functions 

Normally, the value bound to a key on behalf of a particular thread is a pointer to storage 
allocated dynamically on behalf of the calling thread. The destructor functions specified with 
pthread_key_create( ) are intended to be used to free this storage when the thread exits. Thread 
cancelation cleanup handlers cannot be used for this purpose because thread-specific data may 
persist outside the lexical scope in which the cancelation cleanup handlers operate. 

If the value associated with a key needs to be updated during the lifetime of the thread, it may 
be necessary to release the storage associated with the old value before the new value is bound. 
Although the pthread_setspecific( ) function could do this automatically, this feature is not needed 
often enough to justify the added complexity. Instead, the programmer is responsible for freeing 
the stale storage: 

pthread_getspecific(key. Sold); 
new = allocate(); 
destructor(old) ; 
pthread_setspecific(key, new); 

Note: The above example could leak storage if run with asynchronous cancelation enabled. 

No such problems occur in the default cancelation state if no cancelation points 
occur between the get and set. 

There is no notion of a destructor-safe function. If an application does not call pthread_exit () 
from a signal handler, or if it blocks any signal whose handler may call pthread_exit () while 
calling async-unsafe functions, all functions maybe safely called from destructors. 

Non-Idempotent Data Key Creation 

There were requests to make pthread_key_create( ) idempotent with respect to a given key address 
parameter. This would allow applications to call pthread_key_create( ) multiple times for a given 
key address and be guaranteed that only one key would be created. Doing so would require the 
key value to be previously initialized (possibly at compile time) to a known null value and 
would require that implicit mutual-exclusion be performed based on the address and contents of 
the key parameter in order to guarantee that exactly one key would be created. 

Unfortunately, the implicit mutual-exclusion would not be limited to only pthread_key_create(). 
On many implementations, implicit mutual-exclusion would also have to be performed by 
pthread_getspecific( ) and pthread_setspecific( ) in order to guard against using incompletely stored 
or not-yet-visible key values. This could significantly increase the cost of important operations, 
particularly pthread_getspecific (). 

Thus, this proposal was rejected. The pthread_key_create() function performs no implicit 
synchronization. It it the responsibility of the programmer to ensure that it is called exactly once 
per key before use of the key. Several straightforward mechanisms can already be used to 
accomplish this, including calling explicit module initialization functions, using mutexes, and 
using pthread_once(). This places no significant burden on the programmer, introduces no 
possibly confusing ad hoc implicit synchronization mechanism, and potentially allows 
commonly used thread-specific data operations to be more efficient. 

FUTURE DIRECTIONS 

None. 
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29795 SEE ALSO 

29796 pthread_getspecific(), pthread_key_delete(), the System Interface Definitions volume of 

29797 IEEE Std. 1003.1-200x, <pthread.h> 

29798 CHANGE HISTORY 

29799 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

29800 Issue 6 

29801 The pthread_key_create () function is marked as part of the _POSIX_THREADS option. 
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29802 NAME 

29803 pthread_key_delete — thread-specific data key deletion 

29804 SYNOPSIS 

29805 thr #include <pthread.h> 

29806 int pthread_key_delete (pthread_key_t key) ; 

29807 

29808 DESCRIPTION 

29809 The pthread_key_delete( ) function shall delete a thread-specific data key previously returned by 

29810 pthread_key_create(). The thread-specific data values associated with key need not be NULL at 

29811 the time pthread_key_delete() is called. It is the responsibility of the application to free any 

29812 application storage or perform any cleanup actions for data structures related to the deleted key 

29813 or associated thread-specific data in any threads; this cleanup can be done either before or after 

29814 pthread_key_delete() is called. Any attempt to use key following the call to pthread_key_delete() 

29815 results in undefined behavior. 

29816 The pthread_key_delete() function shall be callable from within destructor functions. No 

29817 destructor functions shall be invoked by pthread_key_delete( ). Any destructor function that may 

29818 have been associated with key shall no longer be called upon thread exit. 

29819 RETURN VALUE 

29820 If successful, the pthread_key_delete( ) function shall return zero; otherwise, an error number shall 

29821 be returned to indicate the error. 

29822 ERRORS 

29823 The pthread_key_delete( ) function may fail if: 

29824 [EINVAL] The key value is invalid. 

29825 The pthread_key_delete( ) function does not return an error code of [EINTR]. 

29826 EXAMPLES 

29827 None. 

29828 APPLICATION USAGE 

29829 None. 

29830 RATIONALE 

29831 A thread-specific data key deletion function has been included in order to allow the resources 

29832 associated with an unused thread-specific data key to be freed. Unused thread-specific data keys 

29833 can arise, among other scenarios, when a dynamically loaded module that allocated a key is 

29834 unloaded. 

29835 Portable applications are responsible for performing any cleanup actions needed for data 

29836 structures associated with the key to be deleted, including data referenced by thread-specific 

29837 data values. No such cleanup is done by pthread_key_delete( ). In particular, destructor functions 

29838 are not called. There are several reasons for this division of responsibility: 

29839 1. The associated destructor functions used to free thread-specific data at thread exit time are 

29840 only guaranteed to work correctly when called in the thread that allocated the thread- 

29841 specific data. (Destructors themselves may utilize thread-specific data.) Thus, they cannot 

29842 be used to free thread-specific data in other threads at key deletion time. Attempting to 

29843 have them called by other threads at key deletion time would require other threads to be 

29844 asynchronously interrupted. But since interrupted threads could be in an arbitrary state, 

29845 including holding locks necessary for the destructor to run, this approach would fail. In 

29846 general, there is no safe mechanism whereby an implementation could free thread-specific 

29847 data at key deletion time. 
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29848 2. Even if there were a means of safely freeing thread-specific data associated with keys to be 

29849 deleted, doing so would require that implementations be able to enumerate the threads 

29850 with non-NULL data and potentially keep them from creating more thread-specific data 

29851 while the key deletion is occurring. This special case could cause extra synchronization in 

29852 the normal case, which would otherwise be unnecessary. 

29853 For an application to know that it is safe to delete a key, it has to know that all the threads that 

29854 might potentially ever use the key do not attempt to use it again. For example, it could know this 

29855 if all the client threads have called a cleanup procedure declaring that they are through with the 

29856 module that is being shut down, perhaps by zero'ing a reference count. 

29857 FUTURE DIRECTIONS 

29858 None. 

29859 SEE ALSO 

29860 pthread_key_create( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

29861 <pthread.h> 

29862 CHANGE HISTORY 

29863 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

29864 Issue 6 

29865 The pthread_key_delete( ) function is marked as part of the _POSIX_THREADS option. 
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29866 NAME 

29867 pthread_kill — send a signal to a thread 

29868 SYNOPSIS 

29869 thr #include <signal.h> 

29870 int pthread_ki 11 (pthread_t thread, int sig) ; 

29871 

29872 DESCRIPTION 

29873 The pthread_kill () function is used to request that a signal be delivered to the specified thread. 

29874 As in kill (), if sig is zero, error checking is performed but no signal is actually sent. 

29875 RETURN VALUE 

29876 Upon successful completion, the function shall return a value of zero. Otherwise, the function 

29877 shall return an error number. If the pthreadjdll () function fails, no signal shall be sent. 

29878 ERRORS 

29879 The pthreadjdll () function shall fail if: 

29880 [ESRCH] No thread could be found corresponding to that specified by the given thread 

29881 ID. 

29882 [EINVAL] The value of the sig argument is an invalid or unsupported signal number. 

29883 The pthreadjdll () function does not return an error code of [EINTR], 

29884 EXAMPLES 

29885 None. 

29886 APPLICATION USAGE 

29887 The pthreadjdll () function provides a mechanism for asynchronously directing a signal at a 

29888 thread in the calling process. This could be used, for example, by one thread to affect broadcast 

29889 delivery of a signal to a set of threads. 

29890 Note that pthreadjdll () only causes the signal to be handled in the context of the given thread; 

29891 the signal action (termination or stopping) affects the process as a whole. 

29892 RATIONALE 

29893 None. 

29894 FUTURE DIRECTIONS 

29895 None. 

29896 SEE ALSO 

29897 kill(), pthread_self(), raise(), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

29898 <signal.h> 

29899 CHANGE HISTORY 

29900 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

29901 Issue 6 

29902 The pthreadjdll () function is marked as part of the _POSIX_THREADS option. 

29903 The APPLICATION USAGE section is added. 
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29904 NAME 

29905 pthread_mutex_destroy, pthread_mutex_init — destroy and initialize a mutex 

29906 SYNOPSIS 

29907 thr #include <pthread.h> 

29908 

29909 

29910 

29911 

29912 

29913 DESCRIPTION 

29914 The pthread_miitex_destroy() function destroys the mutex object referenced by mutex-, the mutex 

29915 object becomes, in effect, uninitialized. An implementation may cause pthread_mutex_destroy( ) to 

29916 set the object referenced by mutex to an invalid value. A destroyed mutex object can be re- 

29917 initialized using pthread_mutex_init{ ); the results of otherwise referencing the object after it has 

29918 been destroyed are undefined. 

29919 It shall be safe to destroy an initialized mutex that is unlocked. Attempting to destroy a locked 

29920 mutex results in undefined behavior. 

29921 The pthread_mutex_in.it {) function initializes the mutex referenced by mutex with attributes 

29922 specified by attr. If attr is NULL, the default mutex attributes are used; the effect shall be the 

29923 same as passing the address of a default mutex attributes object. Upon successful initialization, 

29924 the state of the mutex becomes initialized and unlocked. 

29925 Attempting to initialize an already initialized mutex results in undefined behavior. 

29926 In cases where default mutex attributes are appropriate, the macro 

29927 PTHREAD_MUTEX_INITIALIZER can be used to initialize mutexes that are statically allocated. 

29928 The effect is equivalent to dynamic initialization by a call to pthread_mutex_in.it () with parameter 

29929 attr specified as NULL, except that no error checks are performed. 

29930 RETURN VALUE 

29931 If successful, the pthread_mutex_destroy() and pthread_mutex_in.it () functions shall return zero; 

29932 otherwise, an error number shall be returned to indicate the error. 

29933 The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed 

29934 immediately at the beginning of processing for the function and shall cause an error return prior 

29935 to modifying the state of the mutex specified by mutex. 

29936 ERRORS 

29937 The pthread_mutex_destroy( ) function may fail if: 

29938 [EBUSY] The implementation has detected an attempt to destroy the object referenced 

29939 by mutex while it is locked or referenced (for example, while being used in a 

29940 pthread_cond_timedwait( ) or pthread_cond_zvait( )) by another thread. 

29941 [EINVAL] The value specified by mutex is invalid. 

29942 The pthread_mutex_in.it () function shall fail if: 

29943 [EAGAIN] The system lacked the necessary resources (other than memory) to initialize 

29944 another mutex. 

29945 [ENOMEM] Insufficient memory exists to initialize the mutex. 

29946 [EPERM] The caller does not have the privilege to perform the operation. 


int pthread_mutex_destroy(pthread_mutex_t *mutex); 
int pthread_mutex_init(pthread_mutex_t *mutex, 
const pthread_mutexattr_t * attr) ; 
pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER; 


978 


Technical Standard (2000) (Draft February 29, 2000) 




System Interfaces 


pthread_mutex_destroy() 


29947 The pthread_mutex_init( ) function may fail if: 

29948 [EBUSY] The implementation has detected an attempt to re-initialize the object 

29949 referenced by mutex, a previously initialized, but not yet destroyed, mutex. 

29950 [EINVAL] The value specified by attr is invalid. 

29951 These functions do not return an error code of [EINTR]. 

29952 EXAMPLES 

29953 None. 

29954 APPLICATION USAGE 

29955 None. 

29956 RATIONALE 

29957 Alternate Implementations Possible 

29958 This volume of IEEE Std. 1003.1-200x supports several alternative implementations of mutexes. 

29959 An implementation may store the lock directly in the object of type pthread_mutex_t. 

29960 Alternatively, an implementation may store the lock in the heap and merely store a pointer, 

29961 handle, or unique ID in the mutex object. Either implementation has advantages or may be 

29962 required on certain hardware configurations. So that portable code can be written that is 

29963 invariant to this choice, this volume of IEEE Std. 1003.1-200x does not define assignment or 

29964 equality for this type, and it uses the term "initialize” to reinforce the (more restrictive) notion 

29965 that the lock may actually reside in the mutex object itself. 

29966 Note that this precludes an over-specification of the type of the mutex or condition variable and 

29967 motivates the opacity of the type. 

29968 An implementation is permitted, but not required, to have pthread_mntex_destroy() store an 

29969 illegal value into the mutex. This may help detect erroneous programs that try to lock (or 

29970 otherwise reference) a mutex that has already been destroyed. 

29971 Tradeoff Between Error Checks and Performance Supported 

29972 Many of the error checks were made optional in order to let implementations trade off 

29973 performance versus degree of error checking according to the needs of their specific applications 

29974 and execution environment. As a general rule, errors or conditions caused by the system (such as 

29975 insufficient memory) always need to be reported, but errors due to an erroneously coded 

29976 application (such as failing to provide adequate synchronization to prevent a mutex from being 

29977 deleted while in use) are made optional. 

29978 A wide range of implementations is thus made possible. For example, an implementation 

29979 intended for application debugging may implement all of the error checks, but an 

29980 implementation running a single, provably correct application under very tight performance 

29981 constraints in an embedded computer might implement minimal checks. An implementation 

29982 might even be provided in two versions, similar to the options that compilers provide: a full- 

29983 checking, but slower version; and a limited-checking, but faster version. To forbid this 

29984 optionality would be a disservice to users. 

29985 By carefully limiting the use of "undefined behavior" only to things that an erroneous (badly 

29986 coded) application might do, and by defining that resource-not-available errors are mandatory, 

29987 this volume of IEEE Std. 1003.1-200x ensures that a fully-conforming application is portable 

29988 across the full range of implementations, while not forcing all implementations to add overhead 

29989 to check for numerous things that a correct program never does. 
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Why No Limits Defined 

Defining symbols for the maximum number of mutexes and condition variables was considered 
but rejected because the number of these objects may change dynamically. Furthermore, many 
implementations place these objects into application memory; thus, there is no explicit 
maximum. 

Static Initializers for Mutexes and Condition Variables 

Providing for static initialization of statically allocated synchronization objects allows modules 
with private static synchronization variables to avoid runtime initialization tests and overhead. 
Furthermore, it simplifies the coding of self-initializing modules. Such modules are common in 
C libraries, where for various reasons the design calls for self-initialization instead of requiring 
an explicit module initialization function to be called. An example use of static initialization 
follows. 

Without static initialization, a self-initializing routine/oo() might look as follows: 

static pthread_once_t foo_once = PTHREAD_ONCE_INIT; 
static pthread_mutex_t foo_mutex; 

void foo_init() 

{ 

pthread_mutex_init(&foo_mutex, NULL); 

} 


void foo() 

{ 

pthread_once(&foo_once, foo_init); 
pthread_mutex_lock(&foo_mutex); 

/* Do work. */ 

pthread_mutex_unlock(&foo_mutex); 

} 

With static initialization, the same routine could be coded as follows: 

static pthread_mutex_t foo_mutex = PTHREAD_MUTEX_INITIALIZER; 

void foo() 

{ 

pthread_mutex_lock(&foo_mutex) ; 

/* Do work. */ 

pthread_mutex_unlock(&foo_mutex); 

} 

Note that the static initialization both eliminates the need for the initialization test inside 
pthread_once() and the fetch of &cfoo_mutex to learn the address to be passed to 
ptkread_mutex_lock{ ) or pthread_mutex_unlock( ). 

Thus, the C code written to initialize static objects is simpler on all systems and is also faster on a 
large class of systems; those where the (entire) synchronization object can be stored in 
application memory. 

Yet the locking performance question is likely to be raised for machines that require mutexes to 
be allocated out of special memory. Such machines actually have to have mutexes and possibly 
condition variables contain pointers to the actual hardware locks. For static initialization to work 
on such machines, pthread_miitex_lock( ) also has to test whether or not the pointer to the actual 
lock has been allocated. If it has not, pthread_mutex_lock( ) has to initialize it before use. The 
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reservation of such resources can be made when the program is loaded, and hence return codes 
have not been added to mutex locking and condition variable waiting to indicate failure to 
complete initialization. 

This runtime test in pthread_mntex_lock( ) would at first seem to be extra work; an extra test is 
required to see whether the pointer has been initialized. On most machines this would actually 
be implemented as a fetch of the pointer, testing the pointer against zero, and then using the 
pointer if it has already been initialized. While the test might seem to add extra work, the extra 
effort of testing a register is usually negligible since no extra memory references are actually 
done. As more and more machines provide caches, the real expenses are memory references, not 
instructions executed. 

Alternatively, depending on the machine architecture, there are often ways to eliminate all 
overhead in the most important case: on the lock operations that occur after the lock has been 
initialized. This can be done by shifting more overhead to the less frequent operation: 
initialization. Since out-of-line mutex allocation also means that an address has to be 
dereferenced to find the actual lock, one technique that is widely applicable is to have static 
initialization store a bogus value for that address; in particular, an address that causes a machine 
fault to occur. When such a fault occurs upon the first attempt to lock such a mutex, validity 
checks can be done, and then the correct address for the actual lock can be filled in. Subsequent 
lock operations incur no extra overhead since they do not "fault". This is merely one technique 
that can be used to support static initialization, while not adversely affecting the performance of 
lock acquisition. No doubt there are other techniques that are highly machine-dependent. 

The locking overhead for machines doing out-of-line mutex allocation is thus similar for 
modules being implicitly initialized, where it is improved for those doing mutex allocation 
entirely inline. The inline case is thus made much faster, and the out-of-line case is not 
significantly worse. 

Besides the issue of locking performance for such machines, a concern is raised that it is possible 
that threads would serialize contending for initialization locks when attempting to finish 
initializing statically allocated mutexes. (Such finishing would typically involve taking an 
internal lock, allocating a structure, storing a pointer to the structure in the mutex, and releasing 
the internal lock.) First, many implementations would reduce such serialization by hashing on 
the mutex address. Second, such serialization can only occur a bounded number of times. In 
particular, it can happen at most as many times as there are statically allocated synchronization 
objects. Dynamically allocated objects would still be initialized via pthread_mutex_init{) or 
pthread_cond_init (). 

Finally, if none of the above optimization techniques for out-of-line allocation yields sufficient 
performance for an application on some implementation, the application can avoid static 
initialization altogether by explicitly initializing all synchronization objects with the 
corresponding pthread_*_init() functions, which are supported by all implementations. An 
implementation can also document the tradeoffs and advise which initialization technique is 
more efficient for that particular implementation. 

Destroying Mutexes 

A mutex can be destroyed immediately after it is unlocked. For example, consider the following 
code: 

struct obj { 
pthread_mutex_t om; 
int refcnt; 
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30083 obj_done (struct obj *op) 

30084 { 

30085 pthread_mutex_lock (&op-4om) ; 

30086 if (--op—»ref cnt == 0) { 

30087 pthread_mutex_unlock(&op—>om) ; 

30088 (A) pthread_mutex_destroy (&op—»om) ; 

30089 (B) free (op) ; 

30090 } else 

30091 (C) pthread_mutex_unlock (&op—»om) ; 

30092 } 

30093 In this case obj is reference counted and obj_done( ) is called whenever a reference to the object is 

30094 dropped. Implementations are required to allow an object to be destroyed and freed and 

30095 potentially unmapped (for example, lines A and B) immediately after the object is unlocked (line 

30096 C). 

30097 FUTURE DIRECTIONS 

30098 None. 

30099 SEE ALSO 

30100 pthread_miitex_getprioceiling( ), pthread_mntex_lock( ), pthread_mutex_timedlock( ), I 

30101 pthread_mntexattr_getpshared( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

30102 <pthread.h> 

30103 CHANGE HISTORY 

30104 First released in Issue 5. Included for alignment with the POSIX Threads Extension. I 

30105 Issue 6 

30106 The pthread_mntex_destroy() and pthread_mutex_in.it () functions are marked as part of the 

30107 _POSIX_THREADS option. I 

30108 The pthread_mutex_timedlock( ) function is added to the SEE ALSO section for alignment with I 

30109 IEEE Std. 1003.1d-1999. I 
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30110 NAME 

30111 pthread_mutex_getprioceiling, pthread_mutex_setprioceiling — change the priority ceiling of a 

30112 mutex (REALTIME THREADS) 

30113 SYNOPSIS 

30114 tpp #include <pthread.h> 

30115 int pthread_mutex_getprioceiling(const pthread_mutex_t *mutex, 

30116 int * prioceiling) ; 

30117 int pthread_mutex_setprioceiling(pthread_mutex_t *mutex, 

30118 int prioceiling, int * old_ceiling) ; 

30119 

30120 DESCRIPTION 

30121 The pthread_mutex_getprioceiling( ) function shall return the current priority ceiling of the mutex. 

30122 The pthread_mutex_setprioceiling( ) function either locks the mutex if it is unlocked, or blocks until 

30123 it can successfully lock the mutex, then it changes the mutex's priority ceiling and releases the 

30124 mutex. When the change is successful, the previous value of the priority ceiling is returned in 

30125 old_ceiling . The process of locking the mutex need not adhere to the priority protect protocol. 

30126 If the pthread_miitex_setprioceiling( ) function fails, the mutex priority ceiling shall not be 

30127 changed. 

30128 RETURN VALUE 

30129 If successful, the pthread_miitex_getprioceiling( ) and pthread_miitex_setprioceiling( ) functions shall 

30130 return zero; otherwise, an error number shall be returned to indicate the error. 

30131 ERRORS 

30132 The pthread_mutex_getprioceiling( ) and pthread_mutex_setprioceiling( ) functions may fail if: 

30133 [EINVAL] The priority requested by prioceiling is out of range. 

30134 [EINVAL] The value specified by mutex does not refer to a currently existing mutex. 

30135 [EPERM] The caller does not have the privilege to perform the operation. 

30136 These functions do not return an error code of [EINTR]. 

30137 EXAMPLES 

30138 None. 

30139 APPLICATION USAGE 

30140 None. 

30141 RATIONALE 

30142 None. 

30143 FUTURE DIRECTIONS 

30144 None. 

30145 SEE ALSO 

30146 pthread_nmtex_destroy{), pthread_nmtex_lock{), pthreadjnutex_timedlock(), the System Interface I 

30147 Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

30148 CHANGE HISTORY 

30149 First released in Issue 5. Included for alignment with the POSIX Threads Extension. I 

30150 Marked as part of the Realtime Threads Feature Group. I 
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Issue 6 

The pthread_mutex_getprioceiling( ) and pthread_miitex_setprioceiling( ) functions are marked as 
part of the _POSIX_THREAD_PRIO_PROTECT option. 

The [ENOSYS] error condition has been removed as stubs need not be provided if an 
implementation does not support the _POSIX_THREAD_PRIO_PROTECT option. 

The [ENOSYS] error denoting non-support of the priority ceiling protocol for mutexes has been 
removed. This is since if the implementation provides the functions (regardless of whether 
_POSIX_PTHREAD_PRIO_PROTECT is defined), they must function as in the DESCRIPTION 
and therefore the priority ceiling protocol for mutexes is supported. I 

The pthread_mutex_timedlock( ) function is added to the SEE ALSO section for alignment with I 
IEEE Std. 1003.1d-1999. I 
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30162 NAME 

30163 pthread_mutex_init — initialize a mutex 

30164 SYNOPSIS 

30165 thr #include <pthread.h> 

30166 int pthread_mutex_init (pthread_mutex_t *mutex, 

30167 const pthread_mutexattr_t *attr) ; 

30168 pthread_mutex_t mutex = PTHREAD_MUTEX_INITIALIZER; 

30169 

30170 DESCRIPTION 

30171 Refer to p thread jnutex jiestroy {). 
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30172 NAME 

30173 pthread_mutex_lock, pthread_mutex_trylock, pthread_mutex_unlock — lock and unlock a 

30174 mutex 

30175 Notes to Reviewers 

30176 This section zvith side shading zvill not appear in the final copy. - Ed. 

30177 The XSI extensions, which include the RWL extensions, are recommended to become parts of I 

30178 POSIX.l _POSIX_THREADS option in the next draft. I 

30179 SYNOPSIS 

30180 thr #include <pthread.h> 

30181 

30182 

30183 

30184 

30185 DESCRIPTION 

30186 The mutex object referenced by mutex shall be locked by calling pthread_mntex_lock(). If the 

30187 mutex is already locked, the calling thread shall block until the mutex becomes available. This 

30188 operation shall return with the mutex object referenced by mutex in the locked state with the 

30189 calling thread as its owner. 

30190 xsi If the mutex type is PTHREAD_MUTEX_NORMAL, deadlock detection shall not be provided. 

30191 Attempting to relock the mutex causes deadlock. If a thread attempts to unlock a mutex that it 

30192 has not locked or a mutex which is unlocked, undefined behavior results. 

30193 If the mutex type is PTHREAD_MUTEX_ERRORCHECK, then error checking shall be provided. 

30194 If a thread attempts to relock a mutex that it has already locked, an error is returned. If a thread 

30195 attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error is 

30196 returned. 

30197 If the mutex type is PTHREAD_MUTEX_RECURSIVE, then the mutex shall maintain the 

30198 concept of a lock count. When a thread successfully acquires a mutex for the first time, the lock 

30199 count is set to one. Every time a thread relocks this mutex, the lock count is incremented by one. 

30200 Each time the thread unlocks the mutex, the lock count is decremented by one. When the lock 

30201 count reaches zero, the mutex becomes available for other threads to acquire. If a thread 

30202 attempts to unlock a mutex that it has not locked or a mutex which is unlocked, an error is 

30203 returned. 

30204 If the mutex type is PTHREAD_MUTEX_DEFAULT, attempting to recursively lock the mutex 

30205 results in undefined behavior. Attempting to unlock the mutex if it was not locked by the calling 

30206 thread results in undefined behavior. Attempting to unlock the mutex if it is not locked results in 

30207 undefined behavior. 

30208 The pthread_mutex_trylock{ ) function is identical to pthread_mutex_lock( ) except that if the mutex 

30209 object referenced by mutex is currently locked (by any thread, including the current thread), the 

30210 call shall return immediately. 

30211 xsi The pthread_mutex_unlock( ) function releases the mutex object referenced by mutex. The manner 

30212 in which a mutex is released is dependent upon the mutex's type attribute. If there are threads 

30213 blocked on the mutex object referenced by mutex when pthread_mutex_unlock( ) is called, 

30214 resulting in the mutex becoming available, the scheduling policy is used to determine which 

30215 thread shall acquire the mutex. 


int pthread_mutex_lock(pthread_mutex_t *mutex) ; 
int pthread_mutex_trylock(pthread_mutex_t *mutex ); 
int pthread_mutex_unlock(pthread_mutex_t *mutex ); 
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30216 xsi (In the case of PTHREAD_MUTEX_RECURSIVE mutexes, the mutex shall become available 

30217 when the count reaches zero and the calling thread no longer has any locks on this mutex). 

30218 If a signal is delivered to a thread waiting for a mutex, upon return from the signal handler the 

30219 thread shall resume waiting for the mutex as if it was not interrupted. 

30220 RETURN VALUE 

30221 If successful, the pthread_mutex_lock( ) and pthread_mutex_unlock{ ) functions shall return zero; 

30222 otherwise, an error number shall be returned to indicate the error. 

30223 The pthread_mutex_trylock( ) function shall return zero if a lock on the mutex object referenced by 

30224 mutex is acquired. Otherwise, an error number is returned to indicate the error. 

30225 ERRORS 

30226 The pthread_mutex_lock( ) and pthread_mutex_trylock( ) functions shall fail if: 

30227 [EINVAL] The mutex was created with the protocol attribute having the value 

30228 PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than 

30229 the mutex's current priority ceiling. 

30230 The pthread_mutex_trylock( ) function shall fail if: 

30231 [EBUSY] The mutex could not be acquired because it was already locked. 

30232 The pthread_mutex_lock(), pthread_mutex_trylock( ), and pthread_mutex_unlock() functions may 

30233 fail if: 

30234 [EINVAL] The value specified by mutex does not refer to an initialized mutex object. 

30235 xsi [EAGAIN] The mutex could not be acquired because the maximum number of recursive 

30236 locks for mutex has been exceeded. 

30237 The pthread_mutex_lock( ) function may fail if: 

30238 [EDEADLK] The current thread already owns the mutex. 

30239 The pthread_mutex_unlock( ) function may fail if: 

30240 [EPERM] The current thread does not own the mutex. 

30241 These functions do not return an error code of [EINTR]. 

30242 EXAMPLES 

30243 None. 

30244 APPLICATION USAGE 

30245 None. 

30246 RATIONALE 

30247 Mutex objects are intended to serve as a low-level primitive from which other thread 

30248 synchronization functions can be built. As such, the implementation of mutexes should be as 

30249 efficient as possible, and this has ramifications on the features available at the interface. 

30250 The mutex functions and the particular default settings of the mutex attributes have been 

30251 motivated by the desire to not preclude fast, inlined implementations of mutex locking and 

30252 unlocking. 

30253 For example, deadlocking on a double-lock is explicitly allowed behavior in order to avoid 

30254 requiring more overhead in the basic mechanism than is absolutely necessary. (More "friendly" 

30255 mutexes that detect deadlock or that allow multiple locking by the same thread are easily 

30256 constructed by the user via the other mechanisms provided. For example, pthread_self( ) can be 

30257 used to record mutex ownership.) Implementations might also choose to provide such extended 


System Interfaces, Issue 6 


987 



pthread_mutex_lock() 


System Interfaces 


30258 features as options via special mutex attributes. 

30259 Since most attributes only need to be checked when a thread is going to be blocked, the use of 

30260 attributes does not slow the (common) mutex-locking case. 

30261 Likewise, while being able to extract the thread ID of the owner of a mutex might be desirable, it 

30262 would require storing the current thread ID when each mutex is locked, and this could incur 

30263 unacceptable levels of overhead. Similar arguments apply to a mutex_tryunlock operation. 

30264 FUTURE DIRECTIONS 

30265 None. 

30266 SEE ALSO 

30267 pthread_mutex_destroy ( ), pthread_mutex_timedlock( ), the System Interface Definitions volume of I 

30268 IEEE Std. 1003.1-200x, <pthread.h> 

30269 CHANGE HISTORY 

30270 First released in Issue 5. Included for alignment with the POSIX Threads Extension. I 

30271 Issue 6 

30272 The pthread_mutex_lock( ), pthread_mutex_trylock( ), and pthread_mutex_unlock() functions are 

30273 marked as part of the _POSIX_THREADS option. 

30274 The following new requirements on POSIX implementations derive from alignment with the 

30275 Single UNIX Specification: 

30276 • The behavior when attempting to relock a mutex is defined. 

30277 The pthread_mutex_timedlock( ) function is added to the SEE ALSO section for alignment with I 

30278 IEEE Std. 1003.1d-1999. I 
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30279 NAME 

30280 pthread_mutex_setprioceiling — change the priority ceiling of a mutex (REALTIME 

30281 THREADS) 

30282 SYNOPSIS 

30283 tpp #include <pthread.h> 

30284 

30285 

30286 

30287 DESCRIPTION 

30288 Refer to pthread_mutex_getprioceiling (). 


int pthread_mutex_setprioceiling(pthread_mutex_t *mutex, 
int prioceiling, int *old_ceiling) ; 
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30289 NAME 

30290 pthread_mutex_timedlock — lock a mutex (REALTIME THREADS) 

30291 SYNOPSIS 

30292 THR TMO 

30293 

30294 

30295 

30296 

30297 DESCRIPTION I 

30298 The pthread_mutexJimedlock( ) function is called to lock the mutex object referenced by mutex. If I 

30299 the mutex is already locked, the calling thread blocks until the mutex becomes available as in the I 

30300 pthread_mntex_lock( ) function. If the mutex cannot be locked without waiting for another thread I 

30301 to unlock the mutex, this wait shall be terminated when the specified timeout expires. I 

30302 The timeout expires when the absolute time specified by abs_timeout passes, as measured by the I 

30303 clock on which timeouts are based (that is, when the value of that clock equals or exceeds I 

30304 abs_timeont), or if the absolute time specified by absjimeout has already been passed at the time I 

30305 of the call. If the Timers option is supported, the timeout is based on the CLOCK_REALTIME I 

30306 clock; if the Timers option is not supported, the timeout is based on the system clock as returned I 

30307 by the time( ) function. The resolution of the timeout is the resolution of the clock on which it is I 

30308 based. The timespec datatype is defined as a structure in the <time.h> header. I 

30309 Under no circumstance will the function fail with a timeout if the mutex can be locked I 

30310 immediately. The validity of the abs_timeout parameter need not be checked if the mutex can be I 

30311 locked immediately. I 

30312 As a consequence of the priority inheritance rules (for mutexes initialized with the I 

30313 PRIO_INHERIT protocol), if a timed mutex wait is terminated because its timeout expires, the I 

30314 priority of the owner of the mutex will be adjusted as necessary to reflect the fact that this thread I 

30315 is no longer among the threads waiting for the mutex. I 

30316 RETURN VALUE I 

30317 If successful, the pthread_mutex_timedlock( ) function shall return zero; otherwise, an error I 

30318 number shall be returned to indicate the error. I 

30319 ERRORS I 

30320 

30321 

30322 

30323 

30324 

30325 

30326 

30327 

30328 

30329 

30330 XSI 

30331 

30332 
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The pthread_mutex_timedlock() function shall fail if: I 

[EINVAL] The mutex was created with the protocol attribute having the value I 

PTHREAD_PRIO_PROTECT and the calling thread's priority is higher than I 
the mutex' current priority ceiling. I 

[EINVAL] The process or thread would have blocked, and the absjimeout parameter I 

specified a nanoseconds field value less than zero or greater than or equal to I 
1000 million. I 

[ETIMEDOUT] The mutex could not be locked before the specified timeout expired. I 

The pthread_mutexJimedlock () function may fail if: I 

[EINVAL] The value specified by mutex does not refer to an initialized mutex object. I 

[EAGAIN] The mutex could not be acquired because the maximum number of recursive I 

locks for mutex has been exceeded. I 

[EDEADLK] The current thread already owns the mutex. I 
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#include <time.h> 

int pthread_mutex_timedlock(pthread_mutex_t *mutex, 
const struct timespec * abs_timeout ); 
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30333 This function does not return an error code of [EINTR], 

30334 EXAMPLES 

30335 None. 

30336 APPLICATION USAGE 

30337 The pthread_mutex_timedlock( ) function is part of the _POSIX_THREADS and 

30338 _POSIX_TIMEOUTS options and need not be provided on all implementations. 

30339 RATIONALE 

30340 None. 

30341 FUTURE DIRECTIONS 

30342 None. 

30343 SEE ALSO 

30344 pthread_mutex_destroy( ), pthread_mutex_lock(), pthread_mutex_trylock( ), <REFERENCE 

30345 UNDEFINED>(pthread_mutex_unlock), time(), the System Interface Definitions volume of 

30346 IEEE Std. 1003.1-200x, <pthread.h>, <time.h> 

30347 CHANGE HISTORY 

30348 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 

30349 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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30350 NAME 

30351 pthread_mutex_trylock, pthread_mutex_unlock — lock and unlock a mutex 

30352 SYNOPSIS 

30353 thr #include <pthread.h> 

30354 

30355 

30356 

30357 DESCRIPTION 

30358 Refer to pthread_mntex_lock (). 


int pthread_mutex_trylock(pthread_mutex_t *mutex ); 
int pthread_mutex_unlock(pthread_mutex_t *mutex) ; 
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30359 NAME 

30360 pthread_mutexattr_destroy, pthread_mutexattr_init — destroy and initialize mutex attributes 

30361 object 

30362 SYNOPSIS 

30363 thr #include <pthread.h> 

30364 int pthread_mutexattr_destroy (pthread_mutexattr_t * attr) ; 

30365 int pthread_mutexattr_init (pthread_mutexattr_t * attr) ; 

30366 

30367 DESCRIPTION 

30368 The pthreadjnutexattrjiestroy( ) function destroys a mutex attributes object; the object becomes, 

30369 in effect, uninitialized. An implementation may cause pthreadjnutexattr_destroy{) to set the 

30370 object referenced by attr to an invalid value. A destroyed mutex attributes object can be re- 

30371 initialized using pthreadjnutexattr_init{)', the results of otherwise referencing the object after it 

30372 has been destroyed are undefined. 

30373 The pthreadjnutexattrjnit() function initializes a mutex attributes object attr with the default 

30374 value for all of the attributes defined by the implementation. 

30375 The effect of initializing an already initialized mutex attributes object is undefined. 

30376 After a mutex attributes object has been used to initialize one or more mutexes, any function 

30377 affecting the attributes object (including destruction) does not affect any previously initialized 

30378 mutexes. 

30379 RETURN VALUE 

30380 Upon successful completion, pthreadjnutexattrjiestroy( ) and pthreadjnutexattr_init { ) shall 

30381 return zero; otherwise, an error number shall be returned to indicate the error. 

30382 ERRORS 

30383 The pthreadjnutexattr_destroy( ) function may fail if: 

30384 [EINVAL] The value specified by attr is invalid. 

30385 The pthreadjnutexattr_init( ) function may fail if: 

30386 [ENOMEM] Insufficient memory exists to initialize the mutex attributes object. 

30387 These functions do not return an error code of [EINTR]. 

30388 EXAMPLES 

30389 None. 

30390 APPLICATION USAGE 

30391 None. 

30392 RATIONALE 

30393 See pthread_attr_init() for a general explanation of attributes. Attributes objects allow 

30394 implementations to experiment with useful extensions and permit extension of this volume of 

30395 IEEE Std. 1003.1-200x without changing the existing functions. Thus, they provide for future 

30396 extensibility of this volume of IEEE Std. 1003.1-200x and reduce the temptation to standardize 

30397 prematurely on semantics that are not yet widely implemented or understood. 

30398 Examples of possible additional mutex attributes that have been discussed are spin_only, 

30399 limited_spin , no_spin, recursive, and metered. (To explain what the latter attributes might mean: 

30400 recursive mutexes would allow for multiple re-locking by the current owner; metered mutexes 

30401 would transparently keep records of queue length, wait time, and so on.) Since there is not yet 

30402 wide agreement on the usefulness of these resulting from shared implementation and usage 
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experience, they are not yet specified in this volume of IEEE Std. 1003.1-200x. Mutex attributes 
objects, however, make it possible to test out these concepts for possible standardization at a 
later time. 

Mutex Attributes and Performance 

Care has been taken to ensure that the default values of the mutex attributes have been defined 
such that mutexes initialized with the defaults have simple enough semantics so that the locking 
and unlocking can be done with the equivalent of a test-and-set instruction (plus possibly a few 
other basic instructions). 

There is at least one implementation method that can be used to reduce the cost of testing at 
lock-time if a mutex has non-default attributes. One such method that an implementation can 
employ (and this can be made fully transparent to fully conforming POSIX applications) is to 
secretly pre-lock any mutexes that are initialized to non-default attributes. Any later attempt to 
lock such a mutex causes the implementation to branch to the "slow path" as if the mutex were 
unavailable; then, on the slow path, the implementation can do the "real work" to lock a non¬ 
default mutex. The underlying unlock operation is more complicated since the implementation 
never really wants to release the pre-lock on this kind of mutex. This illustrates that, depending 
on the hardware, there may be certain optimizations that can be used so that whatever mutex 
attributes are considered "most frequently used" can be processed most efficiently. 

Process Shared Memory and Synchronization 

The existence of memory mapping functions in this volume of IEEE Std. 1003.1-200x leads to the 
possibility that an application may allocate the synchronization objects from this section in 
memory that is accessed by multiple processes (and therefore, by threads of multiple processes). 

In order to permit such usage, while at the same time keeping the usual case (that is, usage 
within a single process) efficient, a process-shared option has been defined. 

If an implementation supports the _POSIX_THREAD_PROCESS_SHARED option, then the 
process-shared attribute can be used to indicate that mutexes or condition variables may be 
accessed by threads of multiple processes. 

The default setting of PTHREAD_PROCESS_PRIVATE has been chosen for the process-shared 
attribute so that the most efficient forms of these synchronization objects are created by default. 

Synchronization variables that are initialized with the PTHREAD_PROCESS_PRIVATE process- 
shared attribute may only be operated on by threads in the process that initialized them. 
Synchronization variables that are initialized with the PTHREAD_PROCESS_SHARED process- 
shared attribute may be operated on by any thread in any process that has access to it. In 
particular, these processes may exist beyond the lifetime of the initializing process. For example, 
the following code implements a simple counting semaphore in a mapped file that may be used 
by many processes. 

/* sem.h */ 
struct semaphore { 

pthread_mutex_t lock; 
pthread_cond_t nonzero; 
unsigned int count; 

}; 

typedef struct semaphore semaphore_t; 

semaphore_t *semaphore_create(char *semaphore_name); 
semaphore_t *semaphore_open(char *semaphore_name); 
void semaphore_post(semaphore_t *semap); 
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void semaphore_wait(semaphore_t *semap); 
void semaphore_close(semaphored *semap); 

/* sem.c */ 

#include <sys/types.h> 

#include <sys/stat.h> 

#include <sys/mman.h> 

#include <fcntl.h> 

#include <pthread.h> 

#include "sem.h" 

semaphore_t * 

semaphore_create(char *semaphore_name) 

{ 

int fd; 

semaphore_t *semap; 
pthread_mutexattr_t psharedm; 
pthread_condattr_t psharedc; 

fd = open(semaphore_name, 0_RDWR | 0_CREAT | 0_EXCL, 0666); 
if (fd < 0) 

return (NULL); 

(void) ftruncate(fd, sizeof (semaphore_t)); 

(void) pthread_mutexattr_init(Spsharedm); 

(void) pthread_mutexattr_setpshared(Spsharedm, 
PTHREAD_PROCESS_SHARED) ; 

(void) pthread_condattr_init(Spsharedc) ; 

(void) pthread_condattr_setpshared(Spsharedc, 
PTHREAD_PROCESS_SHARED) ; 

semap = (semaphore_t *) mmap(NULL, sizeof (semaphore_t), 
PROT_READ | PROT_WRITE, MAP_SHARED, 
fd, 0); 
close (fd); 

(void) pthread_mutex_init (Ssemap—4lock, Spsharedm); 

(void) pthread_cond_init (Ssemap—^nonzero, Spsharedc); 
semap^count = 0; 
return (semap); 

} 


semaphore_t * 

semaphore_open(char *semaphore_name) 

{ 

int fd; 

semaphore_t *semap; 

fd = open(semaphore_name, 0_RDWR, 0666); 
if (fd < 0) 

return (NULL); 

semap = (semaphore_t *) mmap(NULL, sizeof (semaphore_t), 
PROT_READ | PROT_WRITE, MAP_SHARED, 
fd, 0); 
close (fd); 
return (semap); 

} 
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void 

semaphore_post(semaphore_t *semap) 

{ 

pthread_mutex_lock (&semap-4lock) ; 
if (semap—»count == 0) 

pthread_cond_signal (Ssemapx—^nonzero) ; 
semap^count + + ; 

pthread_mutex_unlock(&semap—4lock) ; 

} 


void 

semaphore_wait(semaphore_t *semap) 

{ 

pthread_mutex_lock (Ssemap—>lock) ; 
while (semap—>count == 0) 

pthread_cond_wait (Ssemap—^nonzero, Ssemap—>lock) ; 
semap—>count —; 

pthread_mutex_unlock (&semap—>lock) ; 

} 


void 

semaphore_close(semaphore_t *semap) 

{ 

munmap((void *) semap, sizeof (semaphore_t)); 

} 

The following code is for three separate processes that create, post, and wait on a semphore in 
the file /tmp/semaphore. Once the file is created, the post and wait programs increment and 
decrement the counting semaphore (waiting and waking as required) even though they did not 
initialize the semaphore. 

/* create.c */ 

#include "pthread.h" 

#include "sem.h" 

int 

main () 

{ 

semaphore_t *semap; 

semap = semaphore_create("/tmp/semaphore"); 
if (semap == NULL) 
exit(1); 

semaphore_close(semap) ; 
return (0); 

} 

/* post */ 

#include "pthread.h" 

#include "sem.h" 

int 

main () 

{ 

semaphore_t *semap; 
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30545 semap = semaphore_open ( "/tmp/semaphore" ) ; 

30546 if (semap == NULL) 

30547 exit (1) ; 

30548 semaphore_post (semap) ; 

30549 semaphore_close (semap) ; 

30550 return (0); 

30551 } 

30552 /* wait */ 

30553 #include "pthread.h" 

30554 #include "sem.h" 

30555 int 

30556 main () 

30557 { 

30558 semaphore_t * semap; 

30559 semap = semaphore_open ( "/tmp/semaphore " ) ; 

30560 if (semap == NULL) 

30561 exit (1) ; 

30562 semaphore_wait (semap) ; 

30563 semaphore_close (semap) ; 

30564 return (0); 

30565 } 

30566 FUTURE DIRECTIONS 

30567 None. 

30568 SEE ALSO 

30569 pthread_cond_destroy( ), pthread_create( ), pthread_mutex_destroy{ ), pthread_mutexattr_destroy( ), the 

30570 System Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

30571 CHANGE HISTORY 

30572 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

30573 Issue 6 

30574 The pthread_miitexattr_destroy( ) and pthreadjnutexattr_init () functions are marked as part of the 

30575 _POSIX_THREADS option. 
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30576 NAME 

30577 pthread_mutexattr_getprioceiling, pthread_mutexattr_setprioceiling — get and set prioceiling 

30578 attribute of mutex attributes object (REALTIME THREADS) 

30579 SYNOPSIS 

30580 tpp #include <pthread.h> 

30581 

30582 

30583 

30584 

30585 

30586 DESCRIPTION 

30587 The pthread_mutexattr_getprioceiling{) and pthread_mutexattr_setprioceiling{) functions, 

30588 respectively, get and set the priority ceiling attribute of a mutex attributes object pointed to by 

30589 attr which was previously created by the function pthreadjmitexattr_init (). 

30590 The prioceiling attribute contains the priority ceiling of initialized mutexes. The values of 

30591 prioceiling are within the maximum range of priorities defined by SCHED_FIFO. 

30592 The prioceiling attribute defines the priority ceiling of initialized mutexes, which is the minimum 

30593 priority level at which the critical section guarded by the mutex is executed. In order to avoid 

30594 priority inversion, the priority ceiling of the mutex is set to a priority higher than or equal to the 

30595 highest priority of all the threads that may lock that mutex. The values of prioceiling are within 

30596 the maximum range of priorities defined under the SCHED_FIFO scheduling policy. 

30597 RETURN VALUE 

30598 Upon successful completion, the pthread_miitexattr_getprioceiling( ) and 

30599 pthread_niiitexattr_setprioceiling( ) functions shall return zero; otherwise, an error number shall be 

30600 returned to indicate the error. 

30601 ERRORS 

30602 The pthread_mutexattr_getprioceiling{) and pthread_mutexattr_setprioceiling{ ) functions may fail if: 

30603 [EINVAL] The value specified by attr or prioceiling is invalid. 

30604 [EPERM] The caller does not have the privilege to perform the operation. 

30605 These functions do not return an error code of [EINTR]. 

30606 EXAMPLES 

30607 None. 

30608 APPLICATION USAGE 

30609 None. 

30610 RATIONALE 

30611 None. 

30612 FUTURE DIRECTIONS 

30613 None. 

30614 SEE ALSO 

30615 pthread_cond_destroy(), pthread_create(), pthread_mutex_destroy( ), the System Interface 

30616 Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 


int pthread_mutexattr_getprioceiling(const pthread_mutexattr_t *attr, 
int * prioceiling) ; 

int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, 
int prioceiling) ; 
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30617 CHANGE HISTORY 

30618 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

30619 Marked as part of the Realtime Threads Feature Group. 

30620 Issue 6 

30621 The pthread_mutexattr_getprioceiling( ) and pthread_mutexattr_setprioceiling( ) functions are 

30622 marked as part of the _POSIX_THREAD_PRIO_PROTECT option. 

30623 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

30624 implementation does not support the _POSIX_THREAD_PRIO_PROTECT option. 

30625 The [ENOTSUP] error condition has been removed since these functions do not have a protocol 

30626 argument. 
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30627 NAME 

30628 pthread_mutexattr_getprotocol, pthread_mutexattr_setprotocol — get and set protocol attribute 

30629 of mutex attributes object (REALTIME THREADS) 

30630 SYNOPSIS 

30631 tppitpi #include <pthread.h> 

30632 

30633 

30634 

30635 

30636 

30637 DESCRIPTION 

30638 The pthread_mntexattr_getprotocol() and pthread_mutexattr_setprotocol{) functions, respectively, 

30639 get and set the protocol attribute of a mutex attributes object pointed to by attr which was 

30640 previously created by the function pthread_mutexattr_in.it (). 

30641 The protocol attribute defines the protocol to be followed in utilizing mutexes. The value of 

30642 tpp protocol may be one of PTHREAD_PRIO_NONE, PTHREAD_PRIO_INHERIT, or 

30643 PTHREAD_PRIO_PROTECT,which are defined by the header <pthread.h>. 

30644 When a thread owns a mutex with the PTHREAD_PRIO_NONE protocol attribute, its priority 

30645 and scheduling are not affected by its mutex ownership. 

30646 tpi When a thread is blocking higher priority threads because of owning one or more mutexes with 

30647 the PTHREAD_PRIO_INHERIT protocol attribute, it executes at the higher of its priority or the 

30648 priority of the highest priority thread waiting on any of the mutexes owned by this thread and 

30649 initialized with this protocol. 

30650 tpp When a thread owns one or more mutexes initialized with the PTHREAD_PRIO_PROTECT 

30651 protocol, it executes at the higher of its priority or the highest of the priority ceilings of all the 

30652 mutexes owned by this thread and initialized with this attribute, regardless of whether other 

30653 threads are blocked on any of these mutexes or not. 

30654 man While a thread is holding a mutex which has been initialized with the 

30655 PTHREAD_PRIO_INHERIT or PTHREAD_PRIO_PROTECT protocol attributes, it shall not be 

30656 subject to being moved to the tail of the scheduling queue at its priority in the event that its 

30657 original priority is changed, such as by a call to sched_setpararn(). Likewise, when a thread 

30658 unlocks a mutex that has been initialized with the PTHREAD_PRIO_INHERIT or 

30659 PTHREAD_PRIO_PROTECT protocol attributes, it shall not be subject to being moved to the tail 

30660 of the scheduling queue at its priority in the event that its original priority is changed. 

30661 If a thread simultaneously owns several mutexes initialized with different protocols, it shall 

30662 execute at the highest of the priorities that it would have obtained by each of these protocols. 

30663 tpi When a thread makes a call to pthread_nmtex_lock( ), the mutex was initialized with the protocol 

30664 attribute having the value PTHREAD_PRIO_INHERIT, when the calling thread is blocked 

30665 because the mutex is owned by another thread, that owner thread shall inherit the priority level 

30666 of the calling thread as long as it continues to own the mutex. The implementation shall update 

30667 its execution priority to the maximum of its assigned priority and all its inherited priorities. 

30668 Furthermore, if this owner thread itself becomes blocked on another mutex, the same priority 

30669 inheritance effect shall be propagated to this other owner thread, in a recursive manner. 


int pthread_mutexattr_getprotocol(const pthread_mutexattr_t *attr, 
int * protocol) ; 

int pthread_mutexattr_setprotocol(pthread_mutexattr_t *attr, 
int protocol) ; 
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30670 RETURN VALUE 

30671 Upon successful completion, the pthread_mutexattr_getprotocol () and 

30672 pthread_mutexattr_setprotocol () functions shall return zero; otherwise, an error number shall be 

30673 returned to indicate the error. 

30674 ERRORS 

30675 The pthread_mutexattr_setprotocol () function shall fail if: 

30676 [ENOTSUP] The value specified by protocol is an unsupported value. 

30677 The pthread_mutexattr_getprotocol () and pthread_mutexattr_setprotocol () functions may fail if: 

30678 [EINVAL] The value specified by attr or protocol is invalid. 

30679 [EPERM] The caller does not have the privilege to perform the operation. 

30680 These functions do not return an error code of [EINTR]. 

30681 EXAMPLES 

30682 None. 

30683 APPLICATION USAGE 

30684 None. 

30685 RATIONALE 

30686 None. 

30687 FUTURE DIRECTIONS 

30688 None. 

30689 SEE ALSO 

30690 pthread_cond_destroy(), pthread_create(), pthread_vmtex_destroy{), the System Interface 

30691 Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

30692 CHANGE HISTORY 

30693 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

30694 Marked as part of the Realtime Threads Feature Group. 

30695 Issue 6 

30696 The pthread_mutexattr_getprotocol{) and pthread_mutexattr_setprotocol () functions are marked as 

30697 part of either the _POSIX_THREAD_PRIO_PROTECT or _POSIX_THREAD_PRIO_INHERIT 

30698 options. 

30699 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

30700 implementation does not support the _POSIX_THREAD_PRIO_PROTECT or 

30701 _POSIX_THREAD_PRIO_INHERIT options. 
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30702 NAME 

30703 pthread_mutexattr_getpshared, pthread_mutexattr_setpshared — get and set process-shared 

30704 attribute 

30705 SYNOPSIS 

30706 thr TSH #include <pthread.h> 

30707 

30708 

30709 

30710 

30711 

30712 DESCRIPTION 

30713 The pthread_mutexattr_getpshared( ) function obtains the value of the process-shared attribute from 

30714 the attributes object referenced by attr. The pthread_mutexattr_setpslmred( ) function is used to set 

30715 the process-shared attribute in an initialized attributes object referenced by attr. 

30716 The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a mutex to be 

30717 operated upon by any thread that has access to the memory where the mutex is allocated, even if 

30718 the mutex is allocated in memory that is shared by multiple processes. If the process-shared 

30719 attribute is PTHREAD_PROCESS_PRIVATE, the mutex shall only be operated upon by threads 

30720 created within the same process as the thread that initialized the mutex; if threads of differing 

30721 processes attempt to operate on such a mutex, the behavior is undefined. The default value of 

30722 the attribute shall be PTHREAD_PROCESS_PRIVATE. 

30723 RETURN VALUE 

30724 Upon successful completion, pthread_mntexattr_setpshared() shall return zero; otherwise, an error 

30725 number shall be returned to indicate the error. 

30726 Upon successful completion, pthread_mntexattr_getpshared() shall return zero and stores the 

30727 value of the process-shared attribute of attr into the object referenced by the pshared parameter. 

30728 Otherwise, an error number shall be returned to indicate the error. 

30729 ERRORS 

30730 The pthread_mutexattr_getpslmred( ) and pthread_miitexattr_setpshared( ) functions may fail if: 

30731 [EINVAL] The value specified by attr is invalid. 

30732 The pthread_mutexattr_setpshared( ) function may fail if: 

30733 [EINVAL] The new value specified for the attribute is outside the range of legal values 

30734 for that attribute. 

30735 These functions do not return an error code of [EINTR]. 

30736 EXAMPLES 

30737 None. 

30738 APPLICATION USAGE 

30739 None. 

30740 RATIONALE 

30741 None. 

30742 FUTURE DIRECTIONS 

30743 None. 


int pthread_mutexattr_getpshared(const pthread_mutexattr_t *attr, 
int * pshared) ; 

int pthread_mutexattr_setpshared(pthread_mutexattr_t *attr, 
int pshared) ; 
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30744 SEE ALSO 

30745 pthread_cond_destroy(), pthread_create (), pthread_mutex_destroy (), pthread_mutexattr_destroy {), the 

30746 System Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

30747 CHANGE HISTORY 

30748 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

30749 Issue 6 

30750 The pthread_mutexattr_getpshared() and pthread_mutexattr_setpshared () functions are marked as 

30751 part of the _POSIX_THREADS and _POSIX_THREAD_PROCESS_SHARED options. 
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30752 NAME 

30753 pthread_mutexattr_gettype, pthread_mutexattr_settype — get or set a mutex type 

30754 Notes to Reviewers 

30755 This section with side shading will not appear in the final copy. - Ed. 

30756 The XSI extensions, which include the RWL extensions, are recommended to become parts of I 

30757 POSIX.l _POSIX_THREADS option in the next draft. I 

30758 SYNOPSIS 

30759 XSI tinclude <pthread.h> 

30760 

30761 

30762 

30763 


int pthread_mutexattr_gettype(const pthread_mutexattr_t *attr, 
int *type) ; 

int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type ); 


30764 DESCRIPTION 

30765 The pthread_mutexattr_gettype( ) and pthread_mutexattr_settype( ) functions, respectively, get and 

30766 set the mutex type attribute. This attribute is set in the type parameter to these functions. The 

30767 default value of the type attribute is PTHREAD_MUTEX_DEFAULT. 


30768 The type of mutex is contained in the type attribute of the mutex attributes. Valid mutex types 

30769 include: 


30770 

30771 

30772 

30773 

30774 


PTHREAD_MUTEX_NORMAL 

This type of mutex does not detect deadlock. A thread attempting to relock this mutex 
without first unlocking it shall deadlock. Attempting to unlock a mutex locked by a 
different thread results in undefined behavior. Attempting to unlock an unlocked mutex 
results in undefined behavior. 


30775 

30776 

30777 

30778 

30779 


PTHREAD_MUTEX_ERRORCHECK 

This type of mutex provides error checking. A thread attempting to relock this mutex 
without first unlocking it shall return with an error. A thread attempting to unlock a mutex 
which another thread has locked shall return with an error. A thread attempting to unlock 
an unlocked mutex shall return with an error. 


30780 

30781 

30782 

30783 

30784 

30785 

30786 

30787 


PTHREAD_MUTEX_RECURSIVE 

A thread attempting to relock this mutex without first unlocking it shall succeed in locking 
the mutex. The relocking deadlock which can occur with mutexes of type 
PTHREAD_MUTEX_NORMAL cannot occur with this type of mutex. Multiple locks of this 
mutex require the same number of unlocks to release the mutex before another thread can 
acquire the mutex. A thread attempting to unlock a mutex which another thread has locked 
shall return with an error. A thread attempting to unlock an unlocked mutex shall return 
with an error. 


30788 

30789 

30790 

30791 

30792 

30793 


PTHREAD_MUTEX_DEFAULT 

Attempting to recursively lock a mutex of this type results in undefined behavior. 
Attempting to unlock a mutex of this type which was not locked by the calling thread 
results in undefined behavior. Attempting to unlock a mutex of this type which is not 
locked results in undefined behavior. An implementation is allowed to map this mutex to 
one of the other mutex types. 
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30807 
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30812 

30813 

30814 

30815 

30816 

30817 

30818 

30819 

30820 

30821 

30822 

30823 

30824 

30825 
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RETURN VALUE 

Upon successful completion, the pthread_mutexattr_gettype( ) function shall return zero and store 
the value of the type attribute of attr into the object referenced by the type parameter. Otherwise, 
an error shall be returned to indicate the error. 

If successful, the pthread_mutexattr_settype() function shall return zero; otherwise, an error 
number shall be returned to indicate the error. 

ERRORS 

The pthread_miitexattr_settype( ) function shall fail if: 

[EINVAL] The value type is invalid. 

The pthread_mutexattr_gettype( ) and pthread_mutexattr_settype( ) functions may fail if: 

[EINVAL] The value specified by attr is invalid. 

These functions do not return an error code of [EINTR], 

EXAMPLES 

None. 

APPLICATION USAGE 

It is advised that an application should not use a PTHREAD_MUTEX_RECURSIVE mutex with 
condition variables because the implicit unlock performed for a pthread_cond_timedwait{) or 
pthread_cond_wait() may not actually release the mutex (if it had been locked multiple times). If 
this happens, no other thread can satisfy the condition of the predicate. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

pthread_cond_timedwait(), pthread_cond_zvait(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <pthread.h> 

CHANGE HISTORY 

First released in Issue 5. 

Issue 6 

The Open Group corrigenda item U033/3 has been applied. The SYNOPSIS for 
pthread_mntexattr_gettype() is updated so that the first argument is of type 
constpthread_mutexattr_t*. 
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30826 NAME 

30827 pthread_mutexattr_init — initialize mutex attributes object 

30828 SYNOPSIS 

30829 thr #include <pthread.h> 

30830 int pthread_mutexattr_init (pthread_mutexattr_t *attr) ; 

30831 

30832 DESCRIPTION 

30833 Refer to pthread_mntexattr_destroy (). 
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30834 NAME 

30835 pthread_mutexattr_setprioceiling — set prioceiling attribute of mutex attributes object 

30836 (REALTIME THREADS) 

30837 SYNOPSIS 

30838 tpp #include <pthread.h> 

30839 int pthread_mutexattr_setprioceiling(pthread_mutexattr_t *attr, 

30840 int prioceiling) ; 

30841 

30842 DESCRIPTION 

30843 Refer to pthread_mutexattr_getprioceiling (). 
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30844 NAME 

30845 pthread_mutexattr_setprotocol — set protocol attribute of mutex attributes object (REALTIME 

30846 THREADS) 

30847 SYNOPSIS 

30848 tppitpi #include <pthread.h> 

30849 int pthread_mutexattr_setprotocol (pthread_mutexattr_t *attr, 

30850 int protocol) ; 

30851 

30852 DESCRIPTION 

30853 Refer to pthread_mutexattr_setprotocol (). 
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30854 NAME 

30855 pthread_mutexattr_setpshared — set process-shared attribute 

30856 SYNOPSIS 

30857 thr TSH #include <pthread.h> 

30858 int pthread_mutexattr_setpshared (pthread_mutexattr_t *attr, 

30859 int pshared) ; 

30860 

30861 DESCRIPTION 

30862 Refer to pthread_mntexattr_getpshared(). 
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30863 NAME 

30864 pthread_mutexattr_settype — set a mutex type 

30865 SYNOPSIS 

30866 xsi #include <pthread.h> 

30867 int pthread_mutexattr_settype(pthread_mutexattr_t *attr, int type ); 

30868 

30869 DESCRIPTION 

30870 Refer to pthread_mntexattr_gettype (). 
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30871 NAME 

30872 pthread_once — dynamic package initialization 

30873 SYNOPSIS 

30874 thr #include <pthread.h> 

30875 

30876 

30877 

30878 

30879 DESCRIPTION 

30880 The first call to pthread_once( ) by any thread in a process, with a given once_control, shall call the 

30881 initjoutine with no arguments. Subsequent calls of pthread_once() with the same once_control 

30882 shall not call the init_rontine. On return from pthread_once( ), it is guaranteed that initjroutine has 

30883 completed. The once_control parameter is used to determine whether the associated initialization 

30884 routine has been called. 

30885 The pthread_once() function is not a cancelation point. However, if initjoutine is a cancelation 

30886 point and is canceled, the effect on once_control shall be as if pthread_once( ) was never called. 

30887 The constant PTHREAD_ONCE_INIT is defined by the header <pthread.h>. 

30888 The behavior of pthread_once( ) is undefined if once_control has automatic storage duration or is 

30889 not initialized by PTHREAD_ONCE_INIT. 

30890 RETURN VALUE 

30891 Upon successful completion, pthread_once() shall return zero; otherwise, an error number shall 

30892 be returned to indicate the error. 

30893 ERRORS 

30894 Notes to Reviewers 

30895 This section zvith side shading will not appear in the final copy. - Ed. 

30896 Dl, XSH, ERN 255 notes that no error is returned for invalid parameters and proposes the 

30897 following: 

30898 [EINVAL] If either once_control or initjoutine is invalid. 

30899 No errors are defined. 

30900 The pthread_once( ) function does not return an error code of [EINTR], 

30901 EXAMPLES 

30902 None. 

30903 APPLICATION USAGE 

30904 None. 

30905 RATIONALE 

30906 Some C libraries are designed for dynamic initialization. That is, the global initialization for the 

30907 library is performed when the first procedure in the library is called. In a single-threaded 

30908 program, this is normally implemented using a static variable whose value is checked on entry 

30909 to a routine, as follows: 

30910 static int random_is_initialized = 0; 

30911 extern int initialize_random () ; 


int pthread_once(pthread_once_t *once_control, 
void (* init_routine) (void)); 
pthread_once_t once_control = PTHREAD_ONCE_INIT; 
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30912 

30913 

30914 

30915 

30916 

30917 

30918 

30919 

30920 

30921 

30922 

30923 

30924 

30925 

30926 

30927 

30928 

30929 

30930 

30931 

30932 

30933 

30934 

30935 

30936 

30937 

30938 

30939 

30940 

30941 

30942 

30943 

30944 

30945 

30946 

30947 

30948 


int random_function() 

{ 

if (random_is_initialized == 0) { 

initialize_random() ; 
random_is_initialized = 1; 

} 

... /* Operations performed after initialization. */ 

} 

To keep the same structure in a multi-threaded program, a new primitive is needed. Otherwise, 
library initialization has to be accomplished by an explicit call to a library-exported initialization 
function prior to any use of the library. 

For dynamic library initialization in a multi-threaded process, a simple initialization flag is not 
sufficient; the flag needs to be protected against modification by multiple threads 
simultaneously calling into the library. Protecting the flag requires the use of a mutex; however, 
mutexes have to be initialized before they are used. Ensuring that the mutex is only initialized 
once requires a recursive solution to this problem. 

The use of pthread_once() not only supplies an implementation-guaranteed means of dynamic 
initialization, it provides an aid to the reliable construction of multi-threaded and realtime 
systems. The preceding example then becomes: 

#include <pthread.h> 

static pthread_once_t random_is_initialized = PTHREAD_ONCE_INIT; 
extern int initialize_random() ; 

int random_function() 

{ 

(void) pthread_once(&random_is_initialized, initialize_random); 

... /* Operations performed after initialization. */ 

} 

Note that a pthread_once_t cannot be an array because some compilers do not accept the 
construct &<array_name>. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

The System Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

CHANGE HISTORY 

First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

Issue 6 

The pthread_once( ) function is marked as part of the _POSIX_THREADS option. 
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30949 NAME 

30950 pthread_rwlock_destroy, pthread_rwlock_init — destroy and initialize a read-write lock object 

30951 Notes to Reviewers 

30952 This section zvith side shading zvill not appear in the final copy. - Ed. 

30953 The XSI extensions, which include the RWL extensions, are recommended to become parts of I 

30954 POSIX.l _POSIX_THREADS option in the next draft. I 

30955 SYNOPSIS I 

30956 RWL #include <pthread.h> | 

30957 

30958 

30959 

30960 

30961 DESCRIPTION 

30962 The pthread_rzvlock_destroy() function shall destroy the read-write lock object referenced by 

30963 rzvlock and release any resources used by the lock. The effect of subsequent use of the lock is I 

30964 undefined until the lock is re-initialized by another call to pthread_rzvlock_init(). An 

30965 implementation may cause pthread_rzvlock_destroy() to set the object referenced by rzvlock to an 

30966 invalid value. Results are undefined if pthread_rzvlock_destroy() is called when any thread holds 

30967 rzvlock. Attempting to destroy an uninitialized read-write lock results in undefined behavior. I 

30968 The pthread_rzvlock_init() function shall allocate any resources required to use the read-write I 

30969 lock referenced by rzvlock and initializes the lock to an unlocked state with attributes referenced I 

30970 by attr. If attr is NULL, the default read-write lock attributes are used; the effect is the same as I 

30971 passing the address of a default read-write lock attributes object. Once initialized, the lock can be 

30972 used any number of times without being re-initialized. Results are undefined if I 

30973 pthread_rzvlock_init () is called specifying an already initialized read-write lock. Results are 

30974 undefined if a read-write lock is used without first being initialized. 

30975 If the pthread_rzvlock_init() function fails, rzvlock is not initialized and the contents of rzvlock are 

30976 undefined. 

30977 Only the object referenced by rzvlock may be used for performing synchronization. The result of I 

30978 referring to copies of that object in calls to pthread_rzvlock_destroy(), pthread_rzvlock_rdlock(), I 

30979 ptkread_rzvlock_timedrdlock (), pthread_rzvlock_timedivrlock( ), pthread_rzvlock_tryrdlock(), I 

30980 pthread_rzvlock_tryzvrlock( ), pthread_rzvlock_nnlock{ ), or pthread_rzvlock_zvrlock( ) is undefined. I 

30981 RETURN VALUE 

30982 If successful, the pthread_rzvlock_destroy() and pthread_rwlock_init{ ) functions shall return zero; 

30983 otherwise, an error number shall be returned to indicate the error. 

30984 The [EBUSY] and [EINVAL] error checks, if implemented, act as if they were performed 

30985 immediately at the beginning of processing for the function and caused an error return prior to 

30986 modifying the state of the read-write lock specified by rzvlock . 

30987 ERRORS 

30988 The pthread_rzvlock_destroy( ) function may fail if: 

30989 [EBUSY] The implementation has detected an attempt to destroy the object referenced 

30990 by rzvlock while it is locked. 

30991 [EINVAL] The value specified by rzvlock is invalid. 


int pthread_rwlock_destroy(pthread_rwlock_t *rwlock) ; 
int pthread_rwlock_init(pthread_rwlock_t *rwlock, 
const pthread_rwlockattr_t *attr) ; 
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30992 

30993 

30994 

30995 

30996 

30997 

30998 

30999 

31000 

31001 

31002 

31003 

31004 

31005 

31006 

31007 

31008 

31009 

31010 

31011 

31012 

31013 

31014 

31015 

31016 

31017 

31018 

31019 

31020 

31021 

31022 

31023 

31024 

31025 

31026 

31027 

31028 

31029 

31030 


The pthread_nvlock_init( ) function shall fail if: 

[EAGAIN] The system lacked the necessary resources (other than memory) to initialize 

another read-write lock. 

[ENOMEM] Insufficient memory exists to initialize the read-write lock. 

[EPERM] The caller does not have the privilege to perform the operation. 

The pthread_rwlock_init( ) function may fail if: 

[EBUSY] The implementation has detected an attempt to re-initialize the object 

referenced by rzvlock, a previously initialized but not yet destroyed read-write 
lock. 

[EINVAL] The value specified by attr is invalid. 

Notes to Reviewers 

This section with side shading will not appear in the final copy. - Ed. 

Dl, XSH, ERN 259 noted that no error return is described for when the argument rzvlock is 
invalid and proposes adding as a may fail case: 

[EINVAL] The value specified by rzvlock is invalid. 

These functions do not return an error code of [EINTR], 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

pthread_rzvlock_rdlock (), pthread_rwlock_timedrdlock {), pthread_rwlock_timedwrlock{), 
pthread_rzvlock_tryrdlock (), pthread_rzvlock_tryzvrlock (), pthread_rzvlock_nnlock (), 
pthread_rzvlock_zvrlock( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

<pthread.h> 

CHANGE HISTORY 

First released in Issue 5. 

Issue 6 

The following changes are made for alignment with IEEE Std. 1003.1j-2000: 

• The margin code in the SYNOPSIS s changed to RWL and the initializer macro is deleted. 

• The DESCRIPTION is updated as follows: 

— It explicitly notes allocation of resources upon initialization of a read-write lock object. 

— A paragraph is added specifying that copies of read-write lock objects may not be used. 

• An [EINVAL] error is added to the ERRORS section for pthread_rzvlock_init( ), indicating that 
the rzvlock value is invalid. 
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• The SEE ALSO section is updated. 
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31032 NAME 

31033 pthread_rwlock_init — initialize a read-write lock object 

31034 SYNOPSIS 

31035 RWL #include <pthread.h> 

31036 int pthread_rwlock_init(pthread_rwlock_t *rwlock, 

31037 const pthread_rwlockattr_t *attr) ; 

31038 

31039 DESCRIPTION 

31040 Refer to pthread_rzvlock_destroy (). 
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31041 NAME 

31042 pthread_rwlock_rdlock, pthread_rwlock_tryrdlock — lock a read-write lock object for reading 

31043 Notes to Reviewers 

31044 This section with side shading will not appear in the final copy. - Ed. 

31045 The XSI extensions, which include the RWL extensions, are recommended to become parts of I 

31046 POSIX.l _POSIX_THREADS option in the next draft. I 

31047 SYNOPSIS I 

31048 RWL #include <pthread.h> | 

31049 int pthread_rwlock_rdlock (pthread_rwlock_t *rwlock) ; 

31050 int pthread_rwlock_tryrdlock (pthread_rwlock_t *rwlock) ; 

31051 

31052 DESCRIPTION 

31053 The pthread_rzvlock_rdlock( ) function shall apply a read lock to the read-write lock referenced by 

31054 nvlock. The calling thread acquires the read lock if a writer does not hold the lock and there are I 

31055 tps no writers blocked on the lock. If the Thread Execution Scheduling option is supported, and the I 

31056 threads involved in the lock are executing with the scheduling policies SCHED_FIFO, I 

31057 SCHED_RR, or SCHED_SPORADIC, the calling thread shall not acquire the lock if a writer I 

31058 holds the lock or if writers of higher or equal priority are blocked on the lock; otherwise, the I 

31059 calling thread shall acquire the lock. If the Thread Execution Scheduling option is not supported, I 

31060 it is implementation-dependent whether the calling thread acquires the lock when a writer does I 

31061 not hold the lock and there are writers blocked on the lock. If a writer holds the lock, the calling I 

31062 thread shall not acquire the read lock. If the read lock is not acquired, the calling thread blocks I 

31063 (that is, it does not return from the pthread_rwlock_rdlock{) call) until it can acquire the lock. I 

31064 Results are undefined if the calling thread holds a write lock on rivlock at the time the call is 

31065 made. 

31066 A thread may hold multiple concurrent read locks on nvlock (that is, successfully call the I 

31067 pthread_rwlock_rdlock() function n times). If so, the application shall ensure that the thread I 

31068 performs matching unlocks (that is, it calls the pthread_rwlock_nnlock() function n times). I 

31069 The maximum number of simultaneous read locks that an implementation guarantees can be I 

31070 applied to a reader/writer lock shall be implementation-dependent. The pthread_nvlock_rdlock( ) I 

31071 function may fail if this maximum would be exceeded. I 

31072 The pthread_nvlock_tryrdlock() function shall apply a read lock as in the pthread_nvlock_rdlock{) I 

31073 function, with the exception that the function shall fail if the equivalent pthread_nvlock_rdlock( ) I 

31074 call would have blocked the calling thread. In no case does the pthread_rwlock_tryrdlock() I 

31075 function ever block; it always either acquires the lock or fails and returns immediately. I 

31076 Results are undefined if any of these functions are called with an uninitialized read-write lock. 

31077 If a signal is delivered to a thread waiting for a read-write lock for reading, upon return from the 

31078 signal handler the thread resumes waiting for the read-write lock for reading as if it was not 

31079 interrupted. 

31080 RETURN VALUE 

31081 If successful, the pthread_nvlock_rdlock( ) function shall return zero; otherwise, an error number 

31082 shall be returned to indicate the error. 

31083 The pthread_nvlock_tryrdlock( ) function shall return zero if the lock for reading on the read-write 

31084 lock object referenced by nvlock is acquired. Otherwise, an error number shall be returned to 

31085 indicate the error. 
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31086 

31087 

31088 

31089 

31090 

31091 

31092 

31093 

31094 

31095 

31096 

31097 

31098 

31099 

31100 

31101 

31102 

31103 

31104 

31105 

31106 

31107 

31108 

31109 

31110 

31111 

31112 

31113 

31114 

31115 

31116 

31117 

31118 

31119 

31120 

31121 

31122 

31123 


ERRORS 

The pthread_nvlock_tryrdlock() function shall fail if: 

[EBUSY] The read-write lock could not be acquired for reading because a writer holds I 

the lock or a writer with the appropriate priority was blocked on it. I 

The pthread_nvlock_rdlock( ) and pthread_rzvlock_tryrdlock( ) functions may fail if: 

[EINVAL] The value specified by rzvlock does not refer to an initialized read-write lock 

object. I 

[EAGAIN] The read lock could not be acquired because the maximum number of read 

locks for rzvlock has been exceeded. 

The pthread_rzvlock-rdlock( ) function may fail if: I 

[EDEADLK] The current thread already owns the read-write lock for writing. I 

These functions do not return an error code of [EINTR], I 

EXAMPLES 

None. 

APPLICATION USAGE 

Applications using these functions may be subject to priority inversion, as discussed in the I 
System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.290, Priority Inversion. I 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

pthread_rzvlock_destroy (), pthread_rzvlock_init (), pthread_rzvlock_timedrdlock (), I 

pthread_rwlock_timedwrlock {), pthread_rzvlock_tryzvrlock (), pthread_rzvlock_nnlock {), I 

pthread_rzvlock_zvrlock( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

<pthread.h> I 

CHANGE HISTORY 

First released in Issue 5. I 

Issue 6 I 

The following changes are made for alignment with IEEE Std. 1003.1j-2000: I 

• The margin code in the SYNOPSIS is changed to RWL. I 

• The DESCRIPTION is updated as follows: I 

— Conditions under which writers have precedence over readers are specified. I 

— Failure of pthread_rzvlock_tryrdlock( ) is clarified. I 

— A paragraph on the maximum number of read locks is added. I 

• In the ERRORS sections, [EBUSY] is modified to take into account write priority, and I 
[EDEADLK] is deleted as a pthread_rzvlock_tryrdlock( ) error. 

• The SEE ALSO section is updated. I 
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31124 NAME 

31125 pthread_rwlock_timedrdlock — lock a read-write lock for reading 

31126 SYNOPSIS 

31127 RWL TMO 

31128 

31129 

31130 

31131 

31132 DESCRIPTION 

31133 The pthread_rwlock_timedrdlock{ ) function applies a read lock to the read-write lock referenced 

31134 by rivlock as in the pthread_rzvlock_rdlock() function. However, if the lock cannot be acquired 

31135 without waiting for other threads to unlock the lock, this wait shall be terminated when the 

31136 specified timeout expires. The timeout expires when the absolute time specified by abs_timeout 

31137 passes, as measured by the clock on which timeouts are based (that is, when the value of that 

31138 clock equals or exceeds abs_timeout), or if the absolute time specified by abs_timeout has already 

31139 been passed at the time of the call. 

31140 tmr If the Timers option is supported, the timeout is based on the CLOCK_REALTIME clock; if the 

31141 Timers option is not supported, the timeout is based on the system clock as returned by the 

31142 time( ) function. The resolution of the timeout is the resolution of the clock on which it is based. 

31143 The timespec data type is defined as a structure in the <time.h> header. Under no circumstances 

31144 shall the function fail with a timeout if the lock can be acquired immediately. The validity of the 

31145 absjimeout parameter need not be checked if the lock can be immediately acquired. 

31146 If a signal that causes a signal handler to be executed is delivered to a thread blocked on a read- 

31147 write lock via a call to pthread_rzvlock_timedrdlock( ), upon return from the signal handler the 

31148 thread shall resume waiting for the lock as if it was not interrupted. 

31149 The calling thread may deadlock if at the time the call is made it holds a write lock on rivlock. 

31150 The results are undefined if this function is called with an uninitialized read-write lock. 

31151 RETURN VALUE 

31152 The pthread_rwlock_timedrdlock( ) function shall return zero if the lock for reading on the read- 

31153 write lock object referenced by rivlock is acquired. Otherwise, an error number shall be returned 

31154 to indicate the error. 

31155 ERRORS 

31156 The pthread_rwlock_timedrdlock{ ) function shall fail if: 

31157 [ETIMEDOUT] The lock could not be acquired before the specified timeout expired. 

31158 The pthread_rivlock_timedrdlock( ) function may fail if: 

31159 [EAGAIN] The read lock could not be acquired because the maximum number of read 

31160 locks for lock would be exceeded. 

31161 [EDEADLK] The calling thread already holds a write lock on rivlock. 

31162 [EINVAL] The value specified by rivlock does not refer to an initialized read-write lock 

31163 object, or the abs_timeout nanosecond value is less than zero or greater than or 

31164 equal to 1 000 million. 

31165 This function does not return an error code of [EINTR], 


#include <pthread.h> 

#include <time.h> 

int pthread_rwlock_timedrdlock(pthread_rwlock_t *rwlock, 
const struct timespec * abs_timeout ); 
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31166 EXAMPLES 

31167 None. 

31168 APPLICATION USAGE 

31169 Applications using this function may be subject to priority inversion, as discussed in the System 

31170 Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.290, Priority Inversion. 

31171 The pthread_rwlock_timedrdlock( ) function is part of the _POSIX_READER_WRITER_LOCKS and 

31172 _POSIX_TIMEOUTS options and need not be provided on all implementations. 

31173 RATIONALE 

31174 None. 

31175 FUTURE DIRECTIONS 

31176 None. 

31177 SEE ALSO 

31178 pthread_nvlock_destroy (), pthread_rzvlock_init (), pthread_nvlock_rdlock (), 

31179 pthread_rivlock_timedwrlock (), pthread_nvlock_tryrdlock (), pthread_rzvlock_tryivrlock (), 

31180 pthread_nvlock_unlock( ), pthread_nvlock_zvrlock( ), the System Interface Definitions volume of 

31181 IEEE Std. 1003.1-200x, <pthread.h>, <time.h> 

31182 CHANGE HISTORY 

31183 First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. 

31184 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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31185 NAME 

31186 pthread_rwlock_timedwrlock — lock a read-write lock for writing 

31187 SYNOPSIS 

31188 RWL TMO 

31189 

31190 

31191 

31192 

31193 DESCRIPTION 

31194 The pthread_rwlock_timedwrlock( ) function applies a write lock to the read-write lock referenced 

31195 by rivlock as in the pthread_rzvlock_zvrlock( ) function. However, if the lock cannot be acquired 

31196 without waiting for other threads to unlock the lock, this wait shall be terminated when the 

31197 specified timeout expires. The timeout expires when the absolute time specified by abs_timeout 

31198 passes, as measured by the clock on which timeouts are based (that is, when the value of that 

31199 clock equals or exceeds abs_timeout), or if the absolute time specified by abs_timeout has already 

31200 been passed at the time of the call. 

31201 tmr If the Timers option is supported, the timeout is based on the CLOCK_REALTIME clock; if the 

31202 Timers option is not supported, the timeout is based on the system clock as returned by the 

31203 time( ) function. The resolution of the timeout is the resolution of the clock on which it is based. 

31204 The timespec data type is defined as a structure in the <time.h> header. Under no circumstances 

31205 shall the function fail with a timeout if the lock can be acquired immediately. The validity of the 

31206 absjimeont parameter need not be checked if the lock can be immediately acquired. 

31207 If a signal that causes a signal handler to be executed is delivered to a thread blocked on a 

31208 reader/writer lock via a call to pthread_rwlock_timedwrlock{ ), upon return from the signal handler 

31209 the thread shall resume waiting for the lock as if it was not interrupted. 

31210 The calling thread may deadlock if at the time the call is made it holds the read-write lock. The 

31211 results are undefined if this function is called with an uninitialized read-write lock. 

31212 RETURN VALUE 

31213 The pthread_riulock_timedwrlock( ) function shall return zero if the lock for writing on the read- 

31214 write lock object referenced by rzvlock is acquired. Otherwise, an error number shall be returned 

31215 to indicate the error. 

31216 ERRORS 

31217 The pthread_rwlock_timedwrlock{ ) function shall fail if: 

31218 [ETIMEDOUT] The lock could not be acquired before the specified timeout expired. 

31219 The pthread_rzulock_timedzurlock( ) function may fail if: 

31220 [EDEADLK] The calling thread already holds the rzvlock. 

31221 [EINVAL] The value specified by rwlock does not refer to an initialized read-write lock 

31222 object, or the absjimeout nanosecond value is less than zero or greater than or 

31223 equal to 1 000 million. 

31224 This function does not return an error code of [EINTR], 


#include <pthread.h> 

#include <time.h> 

int pthread_rwlock_timedwrlock(pthread_rwlock_t * rwlock, 
const struct timespec * abs_timeout ); 
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31225 EXAMPLES 

31226 None. 

31227 APPLICATION USAGE 

31228 Applications using this function may be subject to priority inversion, as discussed in the System 

31229 Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.290, Priority Inversion. 

31230 The pthread_nvlock_timedzvrlock() function is part of the _POSIX_READER_WRITER_LOCKS 

31231 and _POSIX_TIMEOUTS options and need not be provided on all implementations. 

31232 RATIONALE 

31233 None. 

31234 FUTURE DIRECTIONS 

31235 None. 

31236 SEE ALSO 

31237 pthread_nvlock_destroy (), pthread_rzvlock_init (), pthread_nvlock_rdlock (), 

31238 pthread_rwlock_timedrdlock{ ), pthread_nvlock_tryrdlock( ), pthread_nvlock_tryzvrlock( ), 

31239 pthread_nvlock_unlock (), pthread_nulock_wrlock( ), the System Interface Definitions volume of 

31240 IEEE Std. 1003.1-200x, <pthread.h>, <time.h> 

31241 CHANGE HISTORY 

31242 First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. 

31243 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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31244 NAME 

31245 pthread_rwlock_tryrdlock — lock a read-write lock object for reading 

31246 SYNOPSIS 

31247 rwl #include <pthread.h> 

31248 int pthread_rwlock_tryrdlock (pthread_rwlock_t *rwlock) ; 

31249 

31250 DESCRIPTION 

31251 Refer to pthread_nvlock_rdlock (). 
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31252 NAME 

31253 pthread_rwlock_trywrlock, pthread_rwlock_wrlock — lock a read-write lock object for writing 

31254 SYNOPSIS 

31255 RWL #include <pthread.h> 

31256 int pthread_rwlock_trywrlock (pthread_rwlock_t *rzvlock) ; 

31257 int pthread_rwlock_wrlock (pthread_rwlock_t *rzvlock) ; 

31258 

31259 DESCRIPTION 

31260 The pthread_rzvlock_tryzvrlock( ) function shall apply a write lock like the pthread_rzvlock_zvrlock () 

31261 function, with the exception that the function shall fail if any thread currently holds rzvlock (for 

31262 reading or writing). 

31263 The pthread_rzvlock_zvrlock() function shall apply a write lock to the read-write lock referenced 

31264 by rzvlock . The calling thread acquires the write lock if no other thread (reader or writer) holds 

31265 the read-write lock rzvlock. Otherwise, the thread blocks (that is, does not return from the 

31266 pthread_rzvlock_zvrlock() call) until it can acquire the lock. Results are undefined if the calling 

31267 thread holds the read-write lock (whether a read or write lock) at the time the call is made. 

31268 Implementations are allowed to favor writers over readers to avoid writer starvation. 

31269 Results are undefined if any of these functions are called with an uninitialized read-write lock. 

31270 If a signal is delivered to a thread waiting for a read-write lock for writing, upon return from the 

31271 signal handler the thread resumes waiting for the read-write lock for writing as if it was not 

31272 interrupted. 

31273 RETURN VALUE 

31274 The pthread_rzvlock_tryzvrlock( ) function shall return zero if the lock for writing on the read-write 

31275 lock object referenced by rzvlock is acquired. Otherwise, an error number shall be returned to 

31276 indicate the error. 

31277 If successful, the pthread_rzvlock_zvrlock( ) function shall return zero; otherwise, an error number 

31278 shall be returned to indicate the error. 

31279 ERRORS 

31280 The pthread_rzvlock_tryzvrlock( ) function shall fail if: 

31281 [EBUSY] The read-write lock could not be acquired for writing because it was already 

31282 locked for reading or writing. 

31283 The pthread_rzvlock_tryzvrlock( ) and pthread_rzvlock_zvrlock( ) functions may fail if: 

31284 [EINVAL] The value specified by rzvlock does not refer to an initialized read-write lock 

31285 object. 

31286 The pthread_rzvlock_zvrlock( ) function may fail if: 

31287 [EDEADLK] The current thread already owns the read-write lock for writing or reading. 

31288 These functions do not return an error code of [EINTR]. 
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31289 EXAMPLES 

31290 None. 

31291 APPLICATION USAGE 

31292 Applications using these functions may be subject to priority inversion, as discussed in the I 

31293 System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.290, Priority Inversion. I 

31294 RATIONALE 

31295 None. 

31296 FUTURE DIRECTIONS 

31297 None. 

31298 SEE ALSO 

31299 pthread_nvlock_destroy (), pthread_rwlock_in.it {), pthread_nvlock_rdlock( ), I 

31300 pthread_rwlock_timedrdlock (), pthread_riulock_timediurlock( ), pthread_nvlock_tryrdlock( ), I 

31301 pthread_rwlock_unlock( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

31302 <pthread.h> I 

31303 CHANGE HISTORY 

31304 First released in Issue 5. I 

31305 Issue 6 I 

31306 The following changes are made for alignment with IEEE Std. 1003.1j-2000: I 

31307 • The margin code in the SYNOPSIS is changed to RWL. I 

31308 • The [EDEADLK] error is deleted as a pthread_rwlock_trywrlock () error. 

31309 • The SEE ALSO section is updated. I 
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31310 

31311 

31312 

31313 

31314 

31315 

31316 

31317 

31318 

31319 

31320 

31321 

31322 

31323 

31324 

31325 

31326 

31327 

31328 

31329 

31330 

31331 

31332 

31333 

31334 

31335 

31336 

31337 

31338 

31339 

31340 

31341 

31342 

31343 

31344 

31345 

31346 

31347 

31348 

31349 

31350 


NAME 

pthread_rwlock_unlock — unlock a read-write lock object 

SYNOPSIS 

rwl #include <pthread.h> 

int pthread_rwlock_unlock(pthread_rwlock_t *rwlock) ; 


DESCRIPTION 

The pthread_rwlock_unlock{ ) function is called to release a lock held on the read-write lock object 
referenced by rzvlock. Results are undefined if the read-write lock rzvlock is not held by the 
calling thread. 

If this function is called to release a read lock from the read-write lock object and there are other 
read locks currently held on this read-write lock object, the read-write lock object remains in the 
read locked state. If this function releases the last read lock for this read-write lock object, the I 
read-write lock object shall be put in the unlocked state with no owners. I 

If this function is called to release a write lock for this read-write lock object, the read-write lock 
object shall be put in the unlocked state. I 

If there are threads blocked on the lock when it becomes available, the scheduling policy is used I 
tps to determine which thread(s) shall acquire the lock. If the Thread Execution Scheduling option is I 
supported, when threads executing with the scheduling policies SCHED_FIFO, SCHED_RR, or I 
SCHED_SPORADIC are waiting on the lock, they will acquire the lock in priority order when I 
the lock becomes available. For equal priority threads, write locks take precedence over read I 
locks. If the Thread Execution Scheduling option is not supported, it is implementation- I 
dependent whether write locks take precedence over read locks. I 

Results are undefined if any of these functions are called with an uninitialized read-write lock. 

RETURN VALUE 

If successful, the pthread_rzvlock_imlock( ) function shall return zero; otherwise, an error number 
shall be returned to indicate the error. 

ERRORS 

The pthread 

[EINVAL] 

[EPERM] 

The pthread 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 


rzvlock_anlock( ) function may fail if: 

The value specified by rzvlock does not refer to an initialized read-write lock 
object. 

The current thread does not hold a lock on the read-write lock. 
rzvlock_unlock( ) function does not return an error code of [EINTR], 
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31351 

31352 

31353 

31354 

31355 

31356 

31357 

31358 

31359 

31360 

31361 

31362 

31363 

31364 


SEE ALSO 

pthread_nvlock_destroy(), pthread_nvlock_in.it{), pthread_nvlock_rdlock (), 
pthread_rwlock_timedrdlock{), pthread_nvlock_timedwrlock (), pthread_rzvlock_tryrdlock(), 
pthread_nvlock_trywrlock {), pthread_rzvlock_zvrlock( ), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <pthread.h> 

CHANGE HISTORY 

First released in Issue 5. 


Issue 6 

The following changes are made for alignment with IEEE Std. 1003.1j-2000: 

• The margin code in the SYNOPSIS is changed to RWL. 

• The DESCRIPTION is updated as follows: 

— The conditions under which writers have precedence over readers are specified. 
— The concept of read-write lock owner is deleted. 

• The SEE ALSO section is updated. 
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31365 NAME 

31366 pthread_rwlock_wrlock — lock a read-write lock object for writing 

31367 SYNOPSIS 

31368 RWL #include <pthread.h> 

31369 int pthread_rwlock_wrlock (pthread_rwlock_t *nvlock) ; 

31370 

31371 DESCRIPTION 

31372 Refer to pthread_nvlock_tryzvrlock (). 
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31373 NAME 

31374 pthread_rwlockattr_destroy, pthread_rwlockattr_init — destroy and initialize read-write lock 

31375 attributes object I 

31376 SYNOPSIS 

31377 rwl #include <pthread.h> I 

31378 int pthread_rwlockattr_destroy (pthread_rwlockattr_t *attr) ; 

31379 int pthread_rwlockattr_init (pthread_rwlockattr_t *attr) ; 

31380 

31381 DESCRIPTION 

31382 The pthread_nvlockattr_destroy() function shall destroy a read-write lock attributes object. The 

31383 effect of subsequent use of the object is undefined until the object is re-initialized by another call 

31384 to pthread_nvlockattr_init(). An implementation may cause pthread_rzvlockattr_destroy() to set 

31385 the object referenced by attr to an invalid value. 

31386 The pthread_rivlockattr_init( ) function shall initialize a read-write lock attributes object attr with 

31387 the default value for all of the attributes defined by the implementation. 

31388 Results are undefined if pthread_nvlockattr_init( ) is called specifying an already initialized read- 

31389 write lock attributes object. 

31390 After a read-write lock attributes object has been used to initialize one or more read-write locks, 

31391 any function affecting the attributes object (including destruction) does not affect any previously 

31392 initialized read-write locks. 

31393 RETURN VALUE 

31394 If successful, the pthread_nvlockattr_destroy( ) and pthread_rzvlockattr_init( ) functions shall return 

31395 zero; otherwise, an error number shall be returned to indicate the error. 

31396 ERRORS 

31397 The pthread_nulockattr_destroy( ) function may fail if: I 

31398 [EINVAL] The value specified by attr is invalid. 

31399 The pthread_nulockattr_init( ) function shall fail if: 

31400 [ENOMEM] Insufficient memory exists to initialize the read-write lock attributes object. 

31401 These functions do not return an error code of [EINTR]. 

31402 EXAMPLES 

31403 None. 

31404 APPLICATION USAGE 

31405 None. I 

31406 RATIONALE 

31407 None. 

31408 FUTURE DIRECTIONS 

31409 None. 

31410 SEE ALSO 

31411 pthread_nvlock_init( ), pthread_riulockattr_getpshared(), pthread_nvlockattr_setpshared( ), the System I 

31412 Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 
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31413 

31414 

31415 

31416 

31417 

31418 


CHANGE HISTORY 

First released in Issue 5. 

Issue 6 

The following changes are made for alignment with IEEE Std. 1003.1j-2000: 

• The margin code in the SYNOPSIS is changed to RWL. 

• The SEE ALSO section is updated. 
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31419 

31420 

31421 

31422 

31423 

31424 

31425 

31426 

31427 

31428 

31429 

31430 

31431 

31432 

31433 

31434 

31435 

31436 

31437 

31438 

31439 

31440 

31441 

31442 

31443 

31444 

31445 

31446 

31447 

31448 

31449 

31450 

31451 

31452 

31453 

31454 

31455 


NAME 

pthread_rwlockattr_getpshared, pthread_rwlockattr_setpshared — get and set process-shared 
attribute of read-write lock attributes object 

SYNOPSIS 

rwl tsh #include <pthread.h> 

int pthread_rwlockattr_getpshared(const pthread_rwlockattr_t *attr, 
int *pshared) ; 

int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, 
int pshared) ; 


DESCRIPTION 

The process-shared attribute is set to PTHREAD_PROCESS_SHARED to permit a read-write lock 
to be operated upon by any thread that has access to the memory where the read-write lock is 
allocated, even if the read-write lock is allocated in memory that is shared by multiple processes. 

If the process-shared attribute is PTHREAD_PROCESS_PRIVATE, the read-write lock shall only 
be operated upon by threads created within the same process as the thread that initialized the 
read-write lock; if threads of differing processes attempt to operate on such a read-write lock, 
the behavior is undefined. The default value of the process-shared attribute is 
PTHREAD_PROCESS_PRIVATE. 

The pthread_nvlockattr_getpshared( ) function obtains the value of the process-shared attribute from 
the initialized attributes object referenced by attr. The pthread_rwlockattr_setpshared() function is 
used to set the process-shared attribute in an initialized attributes object referenced by attr. I 

Additional attributes, their default values, and the names of the associated functions to get and I 
set those attribute values are implementation-dependent. I 

RETURN VALUE 

Upon successful completion, the pthread_rwlockattr_getpshared() shall return zero and store the 
value of the process-shared attribute of attr into the object referenced by the pshared parameter. 
Otherwise, an error number shall be returned to indicate the error. 

If successful, the pthread_rwlockattr_setpshared{) function shall return zero; otherwise, an error 
number shall be returned to indicate the error. 

ERRORS 

The pthread_nvlockattr_getpshared( ) and pthread_nulockattr_setpshared( ) functions may fail if: 
[EINVAL] The value specified by attr is invalid. 

The pthread_rwlockattr_setpshared( ) function may fail if: 

[EINVAL] The new value specified for the attribute is outside the range of legal values 

for that attribute. 

These functions do not return an error code of [EINTR], 


System Interfaces, Issue 6 


1031 




pthread_rwlockattr_getpshared() 


System Interfaces 


31456 EXAMPLES 

31457 None. 

31458 APPLICATION USAGE 

31459 None. 

31460 RATIONALE 

31461 None. 

31462 FUTURE DIRECTIONS 

31463 None. 

31464 SEE ALSO 

31465 pthread_nvlock_init(), pthread_nvlockattr_destroy( ), pthread_rwlockattr_in.it (), the System Interface I 

31466 Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

31467 CHANGE HISTORY 

31468 First released in Issue 5. I 

31469 Issue 6 I 

31470 The following changes are made for alignment with IEEE Std. 1003.1j-2000: I 

31471 • The margin code in the SYNOPSIS is changed to RWL TSH. I 

31472 • The DESCRIPTION notes that additional attributes are implementation-dependent. 

31473 • The SEE ALSO section is updated. I 
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31474 NAME 

31475 pthread_rwlockattr_init — initialize read-write lock attributes object 

31476 SYNOPSIS 

31477 xsi #include <pthread.h> 

31478 int pthread_rwlockattr_init (pthread_rwlockattr_t *attr) ; 

31479 

31480 DESCRIPTION 

31481 Refer to pthread_nvlockattr_destroy (). 
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31482 NAME 

31483 pthread_rwlockattr_setpshared — set process-shared attribute of read-write lock attributes 

31484 object 

31485 SYNOPSIS 

31486 xsi #include <pthread.h> 

31487 

31488 

31489 

31490 DESCRIPTION 

31491 Refer to pthread_nvlockattr_getpshared (). 


int pthread_rwlockattr_setpshared(pthread_rwlockattr_t *attr, 
int pshared) ; 
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31492 NAME 

31493 pthread_self — get calling thread's ID 

31494 SYNOPSIS 

31495 thr #include <pthread.h> 

31496 pthread_t pthread_self (void) ; 

31497 

31498 DESCRIPTION 

31499 The pthread_self( ) function shall return the thread ID of the calling thread. 

31500 RETURN VALUE 

31501 Refer to the DESCRIPTION. 

31502 ERRORS 

31503 No errors are defined. 

31504 The pthread_self( ) function shall not return an error code of [EINTR], 

31505 EXAMPLES 

31506 None. 

31507 APPLICATION USAGE 

31508 None. 

31509 RATIONALE 

31510 The pthread_self{) function provides a capability similar to the getpid() function for processes 

31511 and the rationale is the same: the creation call does not provide the thread ID to the created 

31512 thread. 

31513 FUTURE DIRECTIONS 

31514 None. 

31515 SEE ALSO 

31516 pthread_create(), pthread_eqnal(), the System Interface Definitions volume of 

31517 IEEE Std. 1003.1-200x, <pthread.h> 

31518 CHANGE HISTORY 

31519 First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

31520 Issue 6 

31521 The pthread_self( ) function is marked as part of the _POSIX_THREADS option. 
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31522 NAME 

31523 pthread_setcancelstate, pthread_setcanceltype, pthread_testcancel — set cancelability state 

31524 SYNOPSIS 

31525 thr #include <pthread.h> 

31526 

31527 

31528 

31529 


int pthread_setcancelstate(int state, int *oldstate) ; 
int pthread_setcanceltype(int type, int *oldtype) ; 
void pthread_testcancel(void) ; 


31530 DESCRIPTION 

31531 The pthread_setcancelstate( ) function shall atomically both set the calling thread's cancelability 

31532 state to the indicated state and return the previous cancelability state at the location referenced 

31533 by oldstate. Legal values for state are PTHREAD_CANCEL_ENABLE and 

31534 PTHREAD_CANCEL_DISABLE. 

31535 The pthread_setcanceltype( ) function shall atomically both set the calling thread's cancelability 

31536 type to the indicated type and return the previous cancelability type at the location referenced by 

31537 oldtype. Legal values for type are PTHREAD_CANCEL_DEFERRED and 

31538 PTHREAD_CANCEL_ASYNCHRONOUS. 

31539 The cancelability state and type of any newly created threads, including the thread in which 

31540 main{) was first invoked, shall be PTHREAD_CANCEL_ENABLE and 

31541 PTHREAD_CANCEL_DEFERRED respectively. 

31542 The pthread_testcancel() function shall create a cancelation point in the calling thread. The 

31543 pthread_testcancel () function shall have no effect if cancelability is disabled. 

31544 RETURN VALUE 

31545 If successful, the pthread_setcancelstate( ) and pthread_setcanceltype( ) functions shall return zero; 

31546 otherwise, an error number shall be returned to indicate the error. 


31547 ERRORS 

31548 The pthread_setcancelstate( ) function may fail if: 

31549 [EINVAL] The specified state is not PTHREAD_CANCEL_ENABLE or 

31550 PTHREAD_CANCEL_DISABLE. 

31551 The pthread_setcanceltype( ) function may fail if: 

31552 [EINVAL] The specified type is not PTHREAD_CANCEL_DEFERRED or 

31553 PTHREAD_CANCEL_ASYNCHRONOUS. 


31554 These functions do not return an error code of [EINTR]. 


31555 EXAMPLES 

31556 None. 

31557 APPLICATION USAGE 

31558 None. 


31559 RATIONALE 

31560 The pthread_setcancelstate( ) and pthread_setcanceltype( ) functions are used to control the points at 

31561 which a thread may be asynchronously canceled. For cancelation control to be usable in modular 

31562 fashion, some rules need to be followed. 


31563 

31564 

31565 


An object can be considered to be a generalization of a procedure. It is a set of procedures and 
global variables written as a unit and called by clients not known by the object. Objects may 
depend on other objects. 
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31566 

31567 

31568 

31569 

31570 

31571 

31572 

31573 

31574 

31575 

31576 

31577 

31578 

31579 

31580 

31581 

31582 

31583 

31584 

31585 

31586 

31587 


First, cancelability should only be disabled on entry to an object, never explicitly enabled. On 
exit from an object, the cancelability state should always be restored to its value on entry to the 
object. 

This follows from a modularity argument: if the client of an object (or the client of an object that 
uses that object) has disabled cancelability, it is because the client does not want to be concerned 
about cleaning up if the thread is canceled while executing some sequence of actions. If an object 
is called in such a state and it enables cancelability and a cancelation request is pending for that 
thread, then the thread is canceled, contrary to the wish of the client that disabled. 

Second, the cancelability type may be explicitly set to either deferred or asynchronous upon entry 
to an object. But as with the cancelability state, on exit from an object the cancelability type 
should always be restored to its value on entry to the object. 

Finally, only functions that are cancel-safe may be called from a thread that is asynchronously 
cancelable. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

pthread_cancel(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 
CHANGE HISTORY 

First released in Issue 5. Included for alignment with the POSIX Threads Extension. 

Issue 6 

The pthread_setcancelstate (), pthread_setcanceltype( ), and pthread_testcancel() functions are marked 
as part of the _POSIX_THREADS option. 
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31588 NAME 

31589 pthread_setconcurrency — set level of concurrency 

31590 SYNOPSIS 

31591 xsi #include <pthread.h> 

31592 int pthread_setconcurrency (int new_level) ; 

31593 

31594 DESCRIPTION 

31595 Refer to pthread_getconcnrrency (). 
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31596 NAME 

31597 pthread_setschedparam — dynamic thread scheduling parameters access 

31598 THREADS) 

31599 SYNOPSIS 

31600 TPS #include <pthread.h> 

31601 

31602 

31603 

31604 DESCRIPTION 

31605 Refer to pthread_getschedparam(). 


int pthread_setschedparam (pthread_t thread, int *pohcy, 
const struct sched_param *param ) ; 


(REALTIME 
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31606 NAME 

31607 pthread_setspecific — thread-specific data management 

31608 SYNOPSIS 

31609 thr #include <pthread.h> 

31610 int pthread_setspecif ic (pthread_key_t key, const void * value) ; 

31611 

31612 DESCRIPTION 

31613 Refer to pthread_getspecific (). 
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31614 NAME 

31615 pthread_sigmask, sigprocmask — examine and change blocked signals 

31616 SYNOPSIS 

31617 #include <signal.h> 

31618 thr int pthread_sigmask (int how, const sigset_t *set, sigset_t *oset); 

31619 int sigprocmask (int how, const sigset_t *set, sigset_t *oset); 

31620 DESCRIPTION 

31621 thr The pthread_sigmask () function is used to examine or change (or both) the calling thread's signal 

31622 mask, regardless of the number of threads in the process. The effect shall be the same as 

31623 described for sigprocmask (), without the restriction that the call be made in a single-threaded 

31624 process. 

31625 In a single-threaded process, the sigprocmask () function allows the calling process to examine or 

31626 change (or both) the signal mask of the calling thread. 

31627 If the argument set is not a null pointer, it points to a set of signals to be used to change the 

31628 currently blocked set. 

31629 The argument hozv indicates the way in which the set is changed, and the application shall I 

31630 ensure it consists of one of the following values: I 

31631 SIG_BLOCK The resulting set shall be the union of the current set and the signal set 

31632 pointed to by set . 

31633 SIG_SETMASK The resulting set shall be the signal set pointed to by set . 

31634 SIG_UNBLOCK The resulting set shall be the intersection of the current set and the 

31635 complement of the signal set pointed to by set . 

31636 If the argument oset is not a null pointer, the previous mask is stored in the location pointed to 

31637 by oset. If set is a null pointer, the value of the argument hozv is not significant and the process' 

31638 signal mask is unchanged; thus the call can be used to enquire about currently blocked signals. 

31639 If there are any pending unblocked signals after the call to sigprocmask (), at least one of those 

31640 signals shall be delivered before the call to sigprocmask () returns. 

31641 It is not possible to block those signals which cannot be ignored. This shall be enforced by the 

31642 system without causing an error to be indicated. 

31643 If any of the SIGFPE, SIGILL, SIGSEGV, or SIGBUS signals are generated while they are blocked, 

31644 the result is undefined, unless the signal was generated by the kill() function, the sigqiieue( ) 

31645 function, or the raise () function. 

31646 If sigprocmask () fails, the thread's signal mask is not changed. 

31647 The use of the sigprocmask () function is unspecified in a multi-threaded process. 

31648 RETURN VALUE 

31649 thr Upon successful completion pthread_sigmask( ) shall return 0; otherwise, it shall return the 

31650 corresponding error number. 

31651 Upon successful completion, sigprocmask () shall return 0; otherwise, -1 shall be returned, errno 

31652 shall be set to indicate the error, and the process' signal mask shall be unchanged. 

31653 ERRORS 

31654 thr The pthread_sigmask () and sigprocmask () functions shall fail if: 

31655 [EINVAL] The value of the hozv argument is not equal to one of the defined values. 
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31656 thr The pthread_sigmask() function shall not return an error code of [EINTR], 

31657 EXAMPLES 

31658 None. 

31659 APPLICATION USAGE 

31660 None. 

31661 RATIONALE 

31662 When a process' signal mask is changed in a signal-catching function that is installed by 

31663 sigadion(), the restoration of the signal mask on return from the signal-catching function 

31664 overrides that change (see sigaction()). If the signal-catching function was installed with 

31665 signal (), it is unspecified whether this occurs. 

31666 See kill () for a discussion of the requirement on delivery of signals. 

31667 FUTURE DIRECTIONS 

31668 None. 

31669 SEE ALSO 

31670 sigadion(), sigaddset{), sigdelset(), sigemptyset(), sigfillset(), sigismember(), sigpending(), 

31671 sigquene(), sigsuspend (), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

31672 <signal.h> 

31673 CHANGE HISTORY 

31674 First released in Issue 3. 

31675 Entry included for alignment with the POSIX.1-1988 standard. 

31676 Issue 4 

31677 The DESCRIPTION is changed to indicate that signals can also be generated by raise( ). 

31678 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

31679 • The type of the arguments set and oset are changed from sigset_t* to const sigset_t*. 

31680 Issue 5 

31681 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 

31682 The pthread_sigmask( ) function is added for alignment with the POSIX Threads Extension. 

31683 Issue 6 

31684 The pthread_sigmask( ) function is marked as part of the _POSIX_THREADS option. 

31685 The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

31686 • The DESCRIPTION is updated to explicitly state the functions which may generate the 

31687 signal. 

31688 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 


1042 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


pthread_spin_destroy() 


31689 NAME 

31690 pthread_spin_destroy, pthread_spin_init — destroy or initialize a spin lock object 

31691 Notes to Reviewers 

31692 This section with side shading will not appear in the final copy. - Ed. 

31693 The pthread_spin_init() [EBUSY] error condition could be generalized to apply to any already 

31694 initialized spin lock. DESCRIPTION text does this. pthread_rwlock_init() [EBUSY] does this in 

31695 Austin Draft 2 (and Draft 3 unless revision is made to align with 1003.lj). May be appropriate to 

31696 file IR against 1003.1j. 

31697 SYNOPSIS 

31698 SPI #include <pthread.h> 

31699 int pthread_spin_destroy (pthread_spinlock_t * lock) ; 

31700 int pthread_spin_init (pthread_spinlock_t * lock, int pshared) ; 

31701 

31702 DESCRIPTION 

31703 The pthread_spin_destroy{) function destroys the spin lock referenced by lock and releases any 

31704 resources used by the lock. The effect of subsequent use of the lock is undefined until the lock is 

31705 reinitialized by another call to pthread_spin_init(). The results are undefined if 

31706 pthread_spin_destroy( ) is called when a thread holds the lock, or if this function is called with an 

31707 uninitialized thread spin lock. 

31708 The pthread_spin_init () function allocates any resources required to use the spin lock referenced 

31709 by lock and initializes the lock to an unlocked state. 

31710 tsh If the Thread Process-Shared Synchronization option is supported and the value of pshared is 

31711 PTHREAD_PROCESS_SHARED, the implementation shall permit the spin lock to be operated 

31712 upon by any thread that has access to the memory where the spin lock is allocated, even if it is 

31713 allocated in memory that is shared by multiple processes. 

31714 If the Thread Process-Shared Synchronization option is supported and the value of pshared is 

31715 PTHREAD_PROCESS_PRIVATE, or if the option is not supported, the spin lock shall only be 

31716 operated upon by threads created within the same process as the thread that initialized the spin 

31717 lock. If threads of differing processes attempt to operate on such a spin lock, the behavior is 

31718 undefined. 

31719 The results are undefined if pthread_spin_init () is called specifying an already initialized spin 

31720 lock. The results are undefined if a spin lock is used without first being initialized. 

31721 If the pthread_spin_init() function fails, the lock is not initialized and the contents of lock are 

31722 undefined. 

31723 Only the object referenced by lock may be used for performing synchronization. 

31724 The result of referring to copies of that object in calls to pthread_spin_destroy(), 

31725 pthread_spin_lock{ ), pthread_spin_trylock( ), or pthread_spin_unlock( ) is undefined. 

31726 RETURN VALUE 

31727 Upon successful completion, these functions shall return zero; otherwise, an error number shall 

31728 be returned to indicate the error. 

31729 ERRORS 

31730 These functions may fail if: 

31731 [EBUSY] The implementation has detected an attempt to initialize or destroy a spin 

31732 lock while it is in use (for example, while being used in a pthread_spin_lock( ) 
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31733 call) by another thread. 

31734 [EINVAL] The value specified by lock is invalid. 

31735 The pthread_spin_init( ) function shall fail if: 

31736 [EAGAIN] The system lacks the necessary resources to initialize another spin lock. 

31737 [ENOMEM] Insufficient memory exists to initialize the lock. 

31738 These functions do not return an error code of [EINTR]. 

31739 EXAMPLES 

31740 None. 

31741 APPLICATION USAGE 

31742 The pthread_spin_destroy() and pthread_spin_init() functions are part of 

31743 _POSIX_SPIN_LOCKS option and need not be provided on all implementations. 

31744 RATIONALE 

31745 None. 

31746 FUTURE DIRECTIONS 

31747 None. 

31748 SEE ALSO 

31749 pthread_spin_lock (), pthread_spin_trylock (), pthread_spin_nnlock( ), the System Interface 

31750 Definitions volume of IEEE Std. 1003.1-200x, «pthread.h» 

31751 CHANGE HISTORY 

31752 First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. 

31753 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 


the 
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31754 NAME 

31755 pthread_spin_init — initialize a spin lock object 

31756 SYNOPSIS 

31757 SPI #include <pthread.h> 

31758 int pthread_spin_init (pthread_spinlock_t * lock, int pshared) ; 

31759 

31760 DESCRIPTION 

31761 Refer to pthread_spin_destroy (). 
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31762 NAME 

31763 pthread_spin_lock, pthread_spin_trylock — lock a spin lock object 

31764 SYNOPSIS 

31765 SPI #include <pthread.h> 

31766 int pthread_spin_lock (pthread_spinlock_t * lock) ; 

31767 int pthread_spin_trylock (pthread_spinlock_t * lock) ; 

31768 

31769 DESCRIPTION 

31770 The pthread_spin_lock() function locks the spin lock referenced by lock. The calling thread 

31771 acquires the lock if it is not held by another thread. Otherwise, the thread spins (that is, does not 

31772 return from the pthread_spin_lock() call) until the lock becomes available. The results are 

31773 undefined if the calling thread holds the lock at the time the call is made. The 

31774 pthread_spin_trylock() function locks the spin lock referenced by lock if it is not held by any 

31775 thread. Otherwise, the function fails. 

31776 The results are undefined if any of these functions is called with an uninitialized spin lock. 

31777 RETURN VALUE 

31778 Upon successful completion, these functions shall return zero; otherwise, an error number shall 

31779 be returned to indicate the error. 

31780 ERRORS 

31781 These functions may fail if: 

31782 [EINVAL] The value specified by lock does not refer to an initialized spin lock object. 

31783 The pthread_spin_lock( ) function may fail if: 

31784 [EDEADLK] The calling thread already holds the lock. 

31785 The pthread_spin_trylock( ) function shall fail if: 

31786 [EBUSY] A thread currently holds the lock. 

31787 These functions do not return an error code of [EINTR]. 

31788 EXAMPLES 

31789 None. 

31790 APPLICATION USAGE 

31791 Applications using this function may be subject to priority inversion, as discussed in the System 

31792 Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.290, Priority Inversion. 

31793 The pthread_spin_lock() and pthread_spin_trylock() functions are part of the 

31794 _POSIX_SPIN_LOCKS option and need not be provided on all implementations. 

31795 RATIONALE 

31796 None. 

31797 FUTURE DIRECTIONS 

31798 None. 

31799 SEE ALSO 

31800 pthread_spin_init(), pthread_spin_destroy(), pthread_spin_unlock(), the System Interface 

31801 Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 
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31802 

31803 

31804 


CHANGE HISTORY 

First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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31805 NAME 

31806 pthread_spin_trylock — lock a spin lock object 

31807 SYNOPSIS 

31808 SPI #include <pthread.h> 

31809 int pthread_spin_trylock (pthread_spinlock_t 

31810 

31811 DESCRIPTION 

31812 Refer to pthread_spin_lock (). 


* lock) ; 
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31813 NAME 

31814 pthread_spin_unlock — unlock a spin lock object 

31815 SYNOPSIS 

31816 SPI #include <pthread.h> 

31817 int pthread_spin_unlock (pthread_spinlock_t * lock) ; 

31818 

31819 DESCRIPTION 

31820 The pthread_spin_unlock () function releases the spin lock referenced by lock which was locked 

31821 via the pthread_spin_lock( ) or pthread_spin_trylock( ) functions. The results are undefined if the 

31822 lock is not held by the calling thread. If there are threads spinning on the lock when 

31823 ptkread_spin_unlock () is called, the lock becomes available and an unspecified spinning thread 

31824 shall acquire the lock. 

31825 The results are undefined if this function is called with an uninitialized thread spin lock. 

31826 RETURN VALUE 

31827 Upon successful completion, the pthread_spin_nnlock( ) function shall return zero; otherwise, an 

31828 error number shall be returned to indicate the error. 

31829 ERRORS 

31830 The pthread_spin_unlock( ) function may fail if: 

31831 [EINVAL] An invalid argument was specified. 

31832 [EPERM] The calling thread does not hold the lock. 

31833 This function does not return an error code of [EINTR], 

31834 EXAMPLES 

31835 None. 

31836 APPLICATION USAGE 

31837 The pthread_spin_unlock () function is part of the _POSIX_SPIN_LOCKS option and need not be 

31838 provided on all implementations. 

31839 RATIONALE 

31840 None. 

31841 FUTURE DIRECTIONS 

31842 None. 

31843 SEE ALSO 

31844 pthread_spin_init( ), pthread_spin_destroy( ), pthread_spin_lock (), pthread_spin_trylock( ), the System 

31845 Interface Definitions volume of IEEE Std. 1003.1-200x, <pthread.h> 

31846 CHANGE HISTORY 

31847 First released in Issue 6. Derived from IEEE Std. 1003.1j-2000. 

31848 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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31849 NAME 

31850 pthread_testcancel — set cancelability state 

31851 SYNOPSIS 

31852 thr #include <pthread.h> 

31853 void pthread_testcancel (void) ; 

31854 

31855 DESCRIPTION 

31856 Refer to pthread_setcancelstate (). 
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31857 NAME 

31858 ptsname — get name of the slave pseudo-terminal device 

31859 SYNOPSIS 

31860 xsi #include <stdlib.h> 

31861 char *ptsname (int fildes) ; 

31862 

31863 DESCRIPTION 

31864 The ptsnamei ) function shall return the name of the slave pseudo-terminal device associated 

31865 with a master pseudo-terminal device. Th e fildes argument is a file descriptor that refers to the 

31866 master device. The ptsname( ) function shall return a pointer to a string containing the path name 

31867 of the corresponding slave device. 

31868 The ptsnamei ) function need not be reentrant. A function that is not required to be reentrant is 

31869 not required to be thread-safe. 

31870 RETURN VALUE 

31871 Upon successful completion, ptsnamei ) shall return a pointer to a string which is the name of the 

31872 pseudo-terminal slave device. Upon failure, ptsnamei) shall return a null pointer. This could 

31873 occur it fildes is an invalid file descriptor or if the slave device name does not exist in the file 

31874 system. 

31875 ERRORS 

31876 No errors are defined. 

31877 EXAMPLES 

31878 None. 

31879 APPLICATION USAGE 

31880 The value returned may point to a static data area that is overwritten by each call to ptsnamei )• 

31881 RATIONALE 

31882 None. 

31883 FUTURE DIRECTIONS 

31884 None. 

31885 SEE ALSO 

31886 grantpti), openi ), ttynamei), nnlockpti), the System Interface Definitions volume of 

31887 IEEE Std. 1003.1-200x, <stdlib.h> 

31888 CHANGE HISTORY 

31889 First released in Issue 4, Version 2. 

31890 Issue 5 

31891 Moved from X/OPEN UNIX extension to BASE. 

31892 A note indicating that this function need not be reentrant is added to the DESCRIPTION. 
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31893 

31894 

31895 

31896 

31897 

31898 

31899 

31900 

31901 

31902 

31903 

31904 

31905 

31906 

31907 

31908 

31909 

31910 

31911 

31912 

31913 

31914 

31915 

31916 

31917 

31918 

31919 

31920 

31921 

31922 

31923 

31924 

31925 

31926 

31927 

31928 


NAME 

putc — put byte on a stream 

SYNOPSIS 

#include <stdio.h> 

int putc(int c, FILE * stream); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The putc () function shall be equivalent to fpntc (), except that if it is implemented as a macro it 
may evaluate stream more than once, so the argument should never be an expression with side 
effects. 

RETURN VALUE 

Refer to fputc (). 

ERRORS 

Refer to fputc(). 

EXAMPLES 

None. 

APPLICATION USAGE 

Because it may be implemented as a macro, putc {) may treat a stream argument with side effects 
incorrectly. In particular, putc(c,*f++) does not necessarily work correctly. Therefore, use of this 
function is not recommended in such situations; fpntc() should be used instead. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

fpntc(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdio.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The APPLICATION USAGE section now states that the use of this function is not recommended 
with a stream argument with side effects. 

The following change is incorporated for alignment with the ISO C standard: 

• The c argument is not allowed to be evaluated more than once. 
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31929 NAME 

31930 putc_unlocked — stdio with explicit client locking 

31931 SYNOPSIS 

31932 TSF #include <stdio.h> 

31933 int putc_unlocked (int c, FILE * stream) ; 

31934 

31935 DESCRIPTION 

31936 Refer to getc_nnlocked(). 
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31937 

31938 

31939 

31940 

31941 

31942 

31943 

31944 

31945 

31946 

31947 

31948 

31949 

31950 

31951 

31952 

31953 

31954 

31955 

31956 

31957 

31958 

31959 

31960 

31961 

31962 

31963 


NAME 

putchar — put byte on stdout stream 

SYNOPSIS 

#include <stdio.h> 
int putchar(int c) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The function call putchar (c) shall be equivalent to putc(c,stdout). 

RETURN VALUE 

Refer to fputc(). 

ERRORS 

Refer to fputc{). 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

putc (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdio.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 
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31964 NAME 

31965 putchar_unlocked — stdio with explicit client locking 

31966 SYNOPSIS 

31967 TSF #include <stdio.h> 

31968 int putchar_unlocked (int c) ; 

31969 

31970 DESCRIPTION 

31971 Refer to getc_nnlocked(). 
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31972 NAME 

31973 putenv — change or add a value to environment 

31974 SYNOPSIS 

31975 xsi tinclude <stdlib.h> 

31976 int putenv (char * string) ; 

31977 

31978 DESCRIPTION 

31979 The putenv () function uses the string argument to set environment variable values. The string 

31980 argument should point to a string of the form "name-value. The putenv () function makes the 

31981 value of the environment variable name equal to value by altering an existing variable or creating 

31982 a new one. In either case, the string pointed to by string becomes part of the environment, so 

31983 altering the string shall change the environment. The space used by string is no longer used once 

31984 a new string-defining name is passed to putenv (). 

31985 The putenv( ) function need not be reentrant. A function that is not required to be reentrant is not 

31986 required to be thread-safe. 

31987 RETURN VALUE 

31988 Upon successful completion, putenv( ) shall return 0; otherwise, it shall return a non-zero value 

31989 and set errno to indicate the error. 

31990 ERRORS 

31991 The putenv( ) function may fail if: 

31992 [ENOMEM] Insufficient memory was available. 

31993 EXAMPLES 

31994 Changing the Value of an Environment Variable 

31995 The following example changes the value of the HOME environment variable to the value 

31996 /usr/home. 

31997 #include <stdlib.h> 

31998 

31999 static char *var = "HOME=/usr/home"; 

32000 int ret; 

32001 ret = putenv (var) ; 

32002 APPLICATION USAGE 

32003 The putenv() function manipulates the environment pointed to by environ, and can be used in 

32004 conjunction with getenv( ). 

32005 This routine may use malloc( ) to enlarge the environment. 

32006 A potential error is to call putenv( ) with an automatic variable as the argument, then return from 

32007 the calling function while string is still part of the environment. 

32008 RATIONALE 

32009 None. 

32010 FUTURE DIRECTIONS 

32011 None. 
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32012 

32013 

32014 

32015 

32016 

32017 

32018 

32019 

32020 

32021 

32022 

32023 

32024 


SEE ALSO 

exec, getenv(), malloc(), setenv(), the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, <stdlib.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The <stdlib.h> header is added to the SYNOPSIS section. 

The type of argument string is changed from char* to const char*. 

Issue 5 

The type of the argument to this function is changed from const char* to char*. This was 
indicated as a FUTURE DIRECTION in previous issues. 

A note indicating that this function need not be reentrant is added to the DESCRIPTION. 
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32025 NAME 

32026 putmsg, putpmsg — send a message on a STREAM (STREAMS) 

32027 SYNOPSIS 

32028 XSR tinclude <stropts.h> 

32029 

32030 

32031 

32032 

32033 

32034 DESCRIPTION 

32035 The putmsg () function shall create a message from a process buffer(s) and send the message to a 

32036 STREAMS file. The message may contain either a data part, a control part, or both. The data and 

32037 control parts are distinguished by placement in separate buffers, as described below. The 

32038 semantics of each part are defined by the STREAMS module that receives the message. 

32039 The putpmsg() function does the same thing as putmsg( ), but the process can send messages in 

32040 different priority bands. Except where noted, all requirements on putmsgO also pertain to 

32041 putpmsgO- 

32042 The fildes argument specifies a file descriptor referencing an open STREAM. The ctlptr and 

32043 dataptr arguments each point to a strbuf structure. 

32044 The ctlptr argument points to the structure describing the control part, if any, to be included in 

32045 the message. The buf member in the strbuf structure points to the buffer where the control 

32046 information resides, and the ten member indicates the number of bytes to be sent. The maxlen 

32047 member is not used by putmsg( ). In a similar manner, the argument dataptr specifies the data, if 

32048 any, to be included in the message. Th e flags argument indicates what type of message should be 

32049 sent and is described further below. 

32050 To send the data part of a message, the application shall ensure that dataptr is not a null pointer I 

32051 and the len member of dataptr is 0 or greater. To send the control part of a message, the I 

32052 application shall ensure that the corresponding values are set for ctlptr. No data (control) part I 

32053 shall be sent if either dataptr (ctlptr) is a null pointer or the len member of dataptr (ctlptr) is set to 

32054 -1. 

32055 For putmsg( ), if a control part is specified and flags is set to RS_HIPRI, a high priority message is 

32056 sent. If no control part is specified, and flags is set to RS_HIPRI, putmsg() fails and sets errno to 

32057 [EINVAL]. If flags is set to 0, a normal message (priority band equal to 0) is sent. If a control part 

32058 and data part are not specified and flags is set to 0, no message is sent and 0 is returned. 

32059 For putpmsg( ), the flags are different. The flags argument is a bitmask with the following 

32060 mutually-exclusive flags defined: MSG_HIPRI and MSG_BAND. If flags is set to 0, putpmsgO 

32061 fails and sets errno to [EINVAL], If a control part is specified and flags is set to MSG_HIPRI and 

32062 band is set to 0, a high-priority message is sent. H flags is set to MSG_HIPRI and either no control 

32063 part is specified or band is set to a non-zero value, putpmsg() fails and sets errno to [EINVAL]. If 

32064 flags is set to MSG_BAND, then a message is sent in the priority band specified by band. If a 

32065 control part and data part are not specified and flags is set to MSG_BAND, no message is sent 

32066 and 0 is returned. 

32067 The putmsg() function blocks if the STREAM write queue is full due to internal flow control 

32068 conditions, with the following exceptions: 

32069 • For high-priority messages, putmsgO does not block on this condition and continues 

32070 processing the message. 


int putmsg(int fildes, const struct strbuf *ctlptr, 
const struct strbuf * dataptr, int flags) ; 
int putpmsg(int fildes, const struct strbuf * ctlptr, 

const struct strbuf * dataptr, int band, int flags) ; 
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32071 

32072 

• For other messages, putmsgO does not block but fails when the write queue is full and 
CLNONBLOCK is set. 

32073 

32074 

32075 

The putmsgi ) function also blocks, unless prevented by lack of internal resources, while waiting 
for the availability of message blocks in the STREAM, regardless of priority or whether 
CLNONBLOCK has been specified. No partial message is sent. 

32076 RETURN VALUE 

32077 Upon successful completion, putmsgi ) and putpmsg () shall return 0; otherwise, they shall return 

32078 -1 and set errno to indicate the error. 

32079 ERRORS 

32080 The putmsgi ) and putpmsgi ) functions shall fail if: 

32081 

32082 

32083 

[EAGAIN] 

A non-priority message was specified, the 0_NONBLOCK flag is set, and the 
STREAM write queue is full due to internal flow control conditions; or buffers 
could not be allocated for the message that was to be created. 

32084 

[EBADF] 

fildes is not a valid file descriptor open for writing. 

32085 

[EINTR] 

A signal was caught during putmsgi )• 

32086 

32087 

32088 

32089 

32090 

[EINVAL] 

An undefined value is specified in flags, or flags is set to RS_HIPRI or 
MSG_HIPRI and no control part is supplied, or the STREAM or multiplexer 
referenced by fildes is linked (directly or indirectly) downstream from a 
multiplexer, or flags is set to MSG_HIPRI and band is non-zero (for putpmsg () 
only). 

32091 

32092 

[ENOSR] 

Buffers could not be allocated for the message that was to be created due to 
insufficient STREAMS memory resources. 

32093 

[ENOSTR] 

A STREAM is not associated with fildes. 

32094 

[ENXIO] 

A hangup condition was generated downstream for the specified STREAM. 

32095 

32096 

[EPIPE] or [EIO] 

Th e fildes argument refers to a STREAMS-based pipe and the other end of the 
pipe is closed. A SIGPIPE signal is generated for the calling thread. 

32097 

32098 

32099 

32100 

32101 

32102 

[ERANGE] 

The size of the data part of the message does not fall within the range 
specified by the maximum and minimum packet sizes of the topmost 
STREAM module. This value is also returned if the control part of the message 
is larger than the maximum configured size of the control part of a message, 
or if the data part of a message is larger than the maximum configured size of 
the data part of a message. 

32103 

32104 

32105 

In addition, putmsgO and putpmsg () shall fail if the STREAM head had processed an 
asynchronous error before the call. In this case, the value of errno does not reflect the result of 
putmsgi ) or putpmsg{ ), but reflects the prior error. 
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32106 EXAMPLES 

32107 Sending a High-Priority Message 

32108 The value of/d is assumed to refer to an open STREAMS file. This call to putmsgO does the 

32109 following: 

32110 1. Creates a high-priority message with a control part and a data part, using the buffers 

32111 pointed to by ctrlbuf and databuf, respectively. 

32112 2. Sends the message to the STREAMS file identified by fd. 

32113 #include <stropts.h> 

32114 #include <string.h> 

32115 

32116 int fd; 

32117 char *ctrlbuf = "This 

32118 char *databuf = "This 

32119 struct strbuf Ctrl; 

32120 struct strbuf data; 

32121 int ret; 

32122 ctrl.buf = ctrlbuf; 

32123 ctrl.len = strlen (ctrlbuf); 

32124 data.buf = databuf; 

32125 data.len = strlen (databuf); 

32126 ret = putmsg (fd, &ctrl, &data, MSG_HIPRI); 

32127 Using putpmsgt ) 

32128 This example has the same effect as the previous example. In this example, however, the 

32129 putpmsg( ) function is used to create and send the message to the STREAMS file. 

32130 #include <stropts.h> 

32131 #include <string.h> 

32132 

32133 int fd; 

32134 char *ctrlbuf = "This 

32135 char *databuf = "This 

32136 struct strbuf Ctrl; 

32137 struct strbuf data; 

32138 int ret; 

32139 ctrl.buf = ctrlbuf; 

32140 ctrl.len = strlen (ctrlbuf); 

32141 data.buf = databuf; 

32142 data.len = strlen (databuf); 

32143 ret = putpmsg (fd, &ctrl, Sdata, 0, MSG_HIPRI); 

32144 APPLICATION USAGE 

32145 None. 


is the control part"; 
is the data part"; 


is the control part"; 
is the data part"; 
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32146 

32147 

32148 

32149 

32150 

32151 

32152 

32153 

32154 

32155 

32156 

32157 

32158 

32159 

32160 

32161 


RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

getmsg (), poll (), read(), write (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 
<stropts.h>. Section 2.6 on page 55 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 

The following text is removed from the DESCRIPTION: "The STREAM head guarantees that the 
control part of a message generated by putmsg () is at least 64 bytes in length". 

Issue 6 

This function is marked as part of the XSI STREAMS Option Group. 

The DESCRIPTION is updated to avoid use of the term "must" for application requirements. 
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32162 NAME 

32163 puts — put a string on standard output 

32164 SYNOPSIS 

32165 #include <stdio.h> 

32166 int puts (const char *s) ; 

32167 DESCRIPTION 

32168 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

32169 conflict between the requirements described here and the ISO C standard is unintentional. This I 

32170 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

32171 The puts( ) function shall write the string pointed to by s, followed by a <newline> character, to 

32172 the standard output stream stdout. The terminating null byte shall not be written. 

32173 cx The st_ctime and stjntime fields of the file shall be marked for update between the successful 

32174 execution of puts( ) and the next successful completion of a call to /flush () or/close ( ) on the same 

32175 stream or a call to exit () or abort (). 

32176 RETURN VALUE 

32177 Upon successful completion, pnts() shall return a non-negative number. Otherwise, it shall 

32178 cx return EOF, shall set an error indicator for the stream, and errno shall be set to indicate the error. 

32179 ERRORS 

32180 Refer to fputc(). 

32181 EXAMPLES 

32182 Printing to Standard Output 

32183 The following example gets the current time, converts it to a string using localtime () and 

32184 asctime( ), and prints it to standard output using puts( ). It then prints the number of minutes to 

32185 an event for which it is waiting. 

32186 #include <time.h> 

32187 #include <stdio.h> 

32188 

32189 time_t now; 

32190 int minutes_to_event; 

32191 

32192 time (Snow) ; 

32193 printf ("The time is "); 

32194 puts (asctime (localtime (Snow) ) ) ; 

32195 printf ("There are %d minutes to the event.\n", 

32196 minutes_to_event) ; 

32197 

32198 APPLICATION USAGE 

32199 The pnts( ) function appends a <newline> character, while fputs( ) does not. 

32200 RATIONALE 

32201 None. 

32202 FUTURE DIRECTIONS 

32203 None. 
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32204 SEE ALSO 

32205 fopen(), fputs(), pntc(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

32206 <stdio.h> 

32207 CHANGE HISTORY 

32208 First released in Issue 1. 

32209 Derived from Issue 1 of the SVID. 

32210 Issue 4 

32211 In the DESCRIPTION, the words "null character" are replaced by "null byte". 

32212 The following change is incorporated for alignment with the ISO C standard: 

32213 • The type of argument s is changed from char* to const char*. 

32214 Issue 6 

32215 Extensions beyond the ISO C standard are now marked. 
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32216 NAME 

32217 pututxline — put an entry into user accounting database 

32218 SYNOPSIS 

32219 xsi #include <utmpx.h> 

32220 struct utmpx *pututxline (const struct utmpx 

32221 

32222 DESCRIPTION 

32223 Ref er to en du t xen t (). 


*utmpx) ; 
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32224 NAME 

32225 putwc — put a wide character on a stream 

32226 SYNOPSIS 

32227 #include <stdio.h> 

32228 #include <wchar.h> 

32229 wint_t putwc (wchar_t wc, FILE * stream); 

32230 DESCRIPTION 

32231 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

32232 conflict between the requirements described here and the ISO C standard is unintentional. This I 

32233 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

32234 The putzvc () function shall be equivalent to fputzvc (), except that if it is implemented as a macro 

32235 it may evaluate stream more than once, so the argument should never be an expression with side 

32236 effects. 

32237 RETURN VALUE 

32238 Refer tofpntzvc (). 

32239 ERRORS 

32240 Refer to fpntzvc (). 

32241 EXAMPLES 

32242 None. 

32243 APPLICATION USAGE 

32244 Because it may be implemented as a macro, putzvc{) may treat a stream argument with side I 

32245 effects incorrectly. In particular, putzuc(zuc/f++) need not work correctly. Therefore, use of this I 

32246 function is not recommended ;fputwc() should be used instead. 

32247 RATIONALE 

32248 None. 

32249 FUTURE DIRECTIONS 

32250 None. 

32251 SEE ALSO 

32252 fputzvc(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <stdio.h>, 

32253 <wchar.h> 

32254 CHANGE HISTORY 

32255 First released as a World-wide Portability Interface in Issue 4. 

32256 Issue 5 

32257 Aligned with ISO/IEC 9899:1990/Amendment 1:1995 (E). Specifically, the type of argument zvc 

32258 is changed from wint_t to wchar_t. 

32259 The Optional Header (OH) marking is removed from <stdio.h>. 
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32260 NAME 

32261 putwchar — put a wide character on stdout stream 

32262 SYNOPSIS 

32263 tinclude <wchar.h> 

32264 wint_t putwchar (wchar_t wc) ; 

32265 DESCRIPTION 

32266 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

32267 conflict between the requirements described here and the ISO C standard is unintentional. This I 

32268 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

32269 The function call putwchar (wc) shall be equivalent to putwc(wc, stdout). 

32270 RETURN VALUE 

32271 Refer to fputwc (). 

32272 ERRORS 

32273 Refer to fputwc(). 

32274 EXAMPLES 

32275 None. 

32276 APPLICATION USAGE 

32277 None. 

32278 RATIONALE 

32279 None. 

32280 FUTURE DIRECTIONS 

32281 None. 

32282 SEE ALSO 

32283 fputwc( ), putivc( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

32284 CHANGE HISTORY 

32285 First released in Issue 4. 

32286 Issue 5 

32287 Aligned with ISO/IEC 9899:1990/Amendment 1:1995 (E). Specifically, the type of argument wc 

32288 is changed from wint_t to wchar_t. 
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32289 NAME 

32290 pwrite, — write on a file 

32291 SYNOPSIS 

32292 #include <unistd.h> 

32293 xsi ssize_t pwrite (int fildes, const void *buf, size_t nbyte, 

32294 off_t offset); 

32295 

32296 DESCRIPTION 

32297 Refer to writ e (). 
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32298 NAME 

32299 qsort — sort a table of data 

32300 SYNOPSIS 

32301 tinclude <stdlib.h> 

32302 void qsort (void *base, size_t nel, size_t width 

32303 int (* compar) (const void *, const void *)); 

32304 DESCRIPTION 

32305 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

32306 conflict between the requirements described here and the ISO C standard is unintentional. This I 

32307 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

32308 The qsort () function sorts an array of nel objects, the initial element of which is pointed to by 

32309 base. The size of each object, in bytes, is specified by the width argument. 

32310 The contents of the array are sorted in ascending order according to a comparison function. The 

32311 compar argument is a pointer to the comparison function, which is called with two arguments I 

32312 that point to the elements being compared. The application shall ensure that the function returns I 

32313 an integer less than, equal to, or greater than 0, if the first argument is considered respectively I 

32314 less than, equal to, or greater than the second. If two members compare as equal, their order in I 

32315 the sorted array is unspecified. I 

32316 RETURN VALUE 

32317 The qsort () function shall return no value. 

32318 ERRORS 

32319 No errors are defined. 

32320 EXAMPLES 

32321 None. 

32322 APPLICATION USAGE 

32323 The comparison function need not compare every byte, so arbitrary data may be contained in 

32324 the elements in addition to the values being compared. 

32325 RATIONALE 

32326 None. 

32327 FUTURE DIRECTIONS 

32328 None. 

32329 SEE ALSO 

32330 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

32331 CHANGE HISTORY 

32332 First released in Issue 1. 

32333 Derived from Issue 1 of the SVID. 

32334 Issue 4 

32335 The following change is incorporated for alignment with the ISO C standard: 

32336 • The arguments to compar are formally defined in the SYNOPSIS section. 

32337 Issue 6 I 

32338 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 


1068 


Technical Standard (2000) (Draft February 29, 2000) 




System Interfaces 


raiseO 


32339 NAME 

32340 raise — send a signal to the executing process 

32341 SYNOPSIS 

32342 #include <signal.h> 

32343 int raise (int sig) ; 

32344 DESCRIPTION 

32345 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

32346 conflict between the requirements described here and the ISO C standard is unintentional. This I 

32347 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

32348 cx The raise ( ) function shall send the signal sig to the executing thread. 

32349 thr The effect of the raise ( ) function is equivalent to calling: 

32350 pthread_kill (pthread_self () , sig); 

32351 

32352 RETURN VALUE 

32353 cx Upon successful completion, 0 shall be returned. Otherwise, a non-zero value shall be returned 

32354 and errno shall be set to indicate the error. 

32355 ERRORS 

32356 The raise () function shall fail if: 

32357 cx [EINVAL] The value of the sig argument is an invalid signal number. 

32358 EXAMPLES 

32359 None. 

32360 APPLICATION USAGE 

32361 None. 

32362 RATIONALE 

32363 The term "thread" is an extension to the ISO C standard. 

32364 FUTURE DIRECTIONS 

32365 None. 

32366 SEE ALSO 

32367 kiU(), sigaction(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <signal.h>, 

32368 <sys/types.h> 

32369 CHANGE HISTORY 

32370 First released in Issue 4. 

32371 Derived from the ANSI C standard. 

32372 Issue 5 

32373 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 

32374 Issue 6 

32375 Extensions beyond the ISO C standard are now marked. 

32376 The following new requirements on POSIX implementations derive from alignment with the 

32377 Single UNIX Specification: 

32378 • In the RETURN VALUE section, the requirement to set errno on error is added. 
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• The [EINVAL] error condition is added. 
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32380 NAME 

32381 rand, rand_r, srand — pseudo-random number generator 

32382 SYNOPSIS 

32383 #include <stdlib.h> 

32384 int rand (void) ; 

32385 TSF int rand_r (unsigned int *seed) ; 

32386 void srand (unsigned int seed); 

32387 DESCRIPTION 

32388 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

32389 conflict between the requirements described here and the ISO C standard is unintentional. This I 

32390 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

32391 The rand() function shall compute a sequence of pseudo-random integers in the range 0 to 

32392 xsi {RAND_MAX} with a period of at least 2 3 ". 

32393 cx The rand( ) function need not be reentrant. A function that is not required to be reentrant is not 

32394 required to be thread-safe. 

32395 tsf The rand_r( ) function shall compute a sequence of pseudo-random integers in the range 0 to 

32396 {RAND_MAX}. (The value of the |RAND_MAX} macro shall be at least 32 767.) 

32397 If rand_r( ) is called with the same initial value for the object pointed to by seed and that object is 

32398 not modified between successive returns and calls to rand_r(), the same sequence shall be 

32399 generated. 

32400 The srand () function uses the argument as a seed for a new sequence of pseudo-random 

32401 numbers to be returned by subsequent calls to rand(). If srand() is then called with the same 

32402 seed value, the sequence of pseudo-random numbers shall be repeated. If rand( ) is called before 

32403 any calls to srand() are made, the same sequence shall be generated as when srand() is first 

32404 called with a seed value of 1. 

32405 The implementation shall behave as if no function defined in this volume of 

32406 IEEE Std. 1003.1-200x calls rand () or srand (). 

32407 RETURN VALUE 

32408 The rand( ) function shall return the next pseudo-random number in the sequence. 

32409 tsf The rand_r( ) function shall return a pseudo-random integer. 

32410 The srand () function shall return no value. 

32411 ERRORS 

32412 No errors are defined. 

32413 EXAMPLES 

32414 Generating a Pseudo-Random Number Sequence 

32415 The following example demonstrates how to generate a sequence of pseudo-random numbers. 

32416 #include <stdio.h> 

32417 #include <stdlib.h> 

32418 

32419 long count, i; 

32420 char *keystr; 

32421 int elementlen, len; 

32422 char c; 
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32423 

32424 

32425 

32426 

32427 

32428 

32429 

32430 

32431 

32432 

32433 

32434 

32435 

32436 

32437 

32438 

32439 

32440 

32441 

32442 

32443 

32444 

32445 

32446 

32447 

32448 

32449 

32450 

32451 

32452 

32453 

32454 

32455 

32456 

32457 

32458 

32459 

32460 

32461 

32462 

32463 

32464 

32465 

32466 

32467 


/* Initial random number generator. */ 
srand(1); 

/* Create keys using only lower case characters */ 
len = 0; 

for (i=0; i<count; i++) { 

while (len < elementlen) { 

c = (char) (rand () % 128); 
if (islower (c)) 

keystr[len++] = c; 

} 

keystr[len] = '\0'; 

printf ("%s Element%0*ld\n", keystr, elementlen, i); 
len = 0; 

} 


Generating the Same Sequence on Different Machines 

The following code defines a pair of functions that could be incorporated into applications 
wishing to ensure that the same sequence of numbers is generated across different machines. 

static unsigned long int next = 1; 

int myrand(void) /* RAND_MAX assumed to be 32767. */ 

{ 

next = next * 1103515245 + 12345; 

return((unsigned int)(next/65536) % 32768); 

} 


void mysrand(unsigned int seed) 

{ 

next = seed; 

} 

APPLICATION USAGE 

The drand48 () function provides a much more elaborate random number generator. 

RATIONALE 

The ISO C standard rand () and srand () functions allow per-process pseudo-random streams 
shared by all threads. Those two functions need not change, but there has to be mutual- 
exclusion that prevents interference between two threads concurrently accessing the random 
number generator. 

With regard to rand(), there are two different behaviors that may be wanted in a multi-threaded 
program: 

1. A single per-process sequence of pseudo-random numbers that is shared by all threads 
that call rand () 

2. A different sequence of pseudo-random numbers for each thread that calls rand () 

This is provided by the modified thread-safe function based on whether the seed value is global 
to the entire process or local to each thread. 

This does not address the known deficiencies of the rand() function implementations, which 
have been approached by maintaining more state. In effect, this specifies new thread-safe forms 
of a deficient function. Since alternatives to rand() are not standardized, they are not modified as 
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32468 

32469 

32470 

32471 

32472 

32473 

32474 

32475 

32476 

32477 

32478 

32479 

32480 

32481 

32482 

32483 

32484 

32485 

32486 

32487 

32488 

32489 

32490 

32491 


part of this volume of IEEE Std. 1003.1-200x. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

drand48(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The definition of srand () is added to the SYNOPSIS section. 

In the DESCRIPTION, the text referring to the period of pseudo-random numbers is marked as 
an extension. 

The example in the APPLICATION USAGE section is updated as follows: 

• To use ISO C standard syntax. 

• To avoid name clashes with standard functions. 

The following changes are incorporated for alignment with the ISO C standard: 

• The argument list of rand () is explicitly defined as void. 

• The argument seed is explicitly defined as unsigned int. 

Issue 5 

The rand_r {) function is included for alignment with the POSIX Threads Extension. 

A note indicating that the mnd () function need not be reentrant is added to the DESCRIPTION. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The rand_r () function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS option. 
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32492 NAME 

32493 random — generate pseudorandom number 

32494 SYNOPSIS 

32495 xsi tinclude <stdlib.h> 

32496 long random (void) ; 

32497 

32498 DESCRIPTION 

32499 Refer to initstate (). 
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32500 NAME 

32501 pread, read, readv — read from a file 

32502 Notes to Reviewers 

32503 This section with side shading will not appear in the final copy. - Ed. 

32504 This function or these functions are recommended to become mandatory parts of POSIX.l in the 

32505 next draft. 

32506 SYNOPSIS 

32507 #include <unistd.h> 

32508 xsi ssize_t pread(int fildes, void *buf, size_t nbyte, off_t offset); 

32509 ssize_t read(int fildes, void *buf, size_t nbyte); 

32510 xsi tinclude <sys/uio.h> 

32511 ssize_t readv (int fildes, const struct iovec *iov, int iovcnt) ; 

32512 

32513 DESCRIPTION 

32514 The read() function attempts to read nbyte bytes from the file associated with the open file 

32515 descriptor, fildes, into the buffer pointed to by bnf. The behavior of multiple concurrent reads on 

32516 the same pipe, FIFO, or terminal device is unspecified. 

32517 If nbyte is zero, the read() function may detect and return errors as described below. In the 

32518 absence of errors, or if error detection is not performed, the read( ) function shall return zero and 

32519 have no other results. 

32520 On files that support seeking (for example, a regular file), the read( ) starts at a position in the file 

32521 given by the file offset associated with fildes. The file offset is incremented by the number of 

32522 bytes actually read. 

32523 Files that do not support seeking—for example, terminals—always read from the current 

32524 position. The value of a file offset associated with such a file is undefined. 

32525 No data transfer shall occur past the current end-of-file. If the starting position is at or after the 

32526 end-of-file, 0 shall be returned. If the file refers to a device special file, the result of subsequent 

32527 read( ) requests is implementation-dependent. 

32528 If the value of nbyte is greater than {SSIZE_MAX}, the result is implementation-dependent. 

32529 When attempting to read from an empty pipe or FIFO: 

32530 • If no process has the pipe open for writing, read( ) shall return 0 to indicate end-of-file. 

32531 • If some process has the pipe open for writing and 0_NONBFOCK is set, read() shall return 

32532 -1 and set errno to [EAGAIN]. 

32533 • If some process has the pipe open for writing and 0_NONBEOCK is clear, read () shall block 

32534 the calling thread until some data is written or the pipe is closed by all processes that had the 

32535 pipe open for writing. 

32536 When attempting to read a file (other than a pipe or FIFO) that supports non-blocking reads and 

32537 has no data currently available: 

32538 • If 0_NONBFOCK is set, read () shall return -1 and set errno to [EAGAIN]. 

32539 • If 0_NONBFOCK is clear, read() shall block the calling thread until some data becomes 

32540 available. 
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32541 

32542 

32543 

32544 

32545 

32546 

32547 

32548 

32549 

32550 

32551 

32552 

32553 

32554 

32555 

32556 

32557 

32558 

32559 

32560 

32561 

32562 

32563 

32564 

32565 

32566 

32567 

32568 

32569 

32570 

32571 

32572 

32573 

32574 

32575 

32576 

32577 

32578 

32579 

32580 

32581 

32582 

32583 

32584 

32585 

32586 

32587 


• The use of the 0_N0NBL0CK flag has no effect if there is some data available. 

The read( ) function reads data previously written to a file. If any portion of a regular file prior to 
the end-of-file has not been written, read( ) shall return bytes with value 0. For example, lseek () 
allows the file offset to be set beyond the end of existing data in the file. If data is later written at 
this point, subsequent reads in the gap between the previous end of data and the newly written 
data shall return bytes with value 0 until data is written into the gap. 

Upon successful completion, where nbyte is greater than 0, read() shall mark for update the 
st_atime field of the file, and shall return the number of bytes read. This number shall never be 
greater than nbyte. The value returned may be less than nbyte if the number of bytes left in the 
file is less than nbyte, if the read( ) request was interrupted by a signal, or if the file is a pipe or 
FIFO or special file and has fewer than nbyte bytes immediately available for reading. For 
example, a read( ) from a file associated with a terminal may return one typed line of data. 

If a read() is interrupted by a signal before it reads any data, it shall return -1 with errno set to 
[EINTR], 

If a read( ) is interrupted by a signal after it has successfully read some data, it shall return the 
number of bytes read. 

xsr A read() from a STREAMS file can read data in three different modes: byte-stream mode, 
message-nondiscard mode, and message-discard mode. The default is byte-stream mode. This can 
be changed using the I_SRDOPT ioctl () request, and can be tested with the I_GRDOPT ioctl (). In 
byte-stream mode, read() retrieves data from the STREAM until as many bytes as were 
requested are transferred, or until there is no more data to be retrieved. Byte-stream mode 
ignores message boundaries. 

In STREAMS message-nondiscard mode, read{) retrieves data until as many bytes as were 
requested are transferred, or until a message boundary is reached. If read() does not retrieve all 
the data in a message, the remaining data is left on the STREAM, and can be retrieved by the 
next read( ) call. Message-discard mode also retrieves data until as many bytes as were requested 
are transferred, or a message boundary is reached. However, unread data remaining in a 
message after the read() returns is discarded, and is not available for a subsequent read(), 
readv( ), or getmsg( ) call. 

How read() handles zero-byte STREAMS messages is determined by the current read mode 
setting. In byte-stream mode, read() accepts data until it has read nbyte bytes, or until there is no 
more data to read, or until a zero-byte message block is encountered. The read() function shall 
then return the number of bytes read, and place the zero-byte message back on the STREAM to 
be retrieved by the next read(), readv( ), or getmsg( ). In message-nondiscard mode or message- 
discard mode, a zero-byte message shall return 0 and the message shall be removed from the 
STREAM. When a zero-byte message is read as the first message on a STREAM, the message 
shall be removed from the STREAM and 0 shall be returned, regardless of the read mode. 

A read( ) from a STREAMS file shall return the data in the message at the front of the STREAM 
head read queue, regardless of the priority band of the message. 

By default, STREAMS are in control-normal mode, in which a read( ) from a STREAMS file can 
only process messages that contain a data part but do not contain a control part. The read() shall 
fail if a message containing a control part is encountered at the STREAM head. This default 
action can be changed by placing the STREAM in either control-data mode or control-discard 
mode with the I_SRDOPT ioctl () command. In control-data mode, read() converts any control 
part to data and passes it to the application before passing any data part originally present in the 
same message. In control-discard mode, read() shall discard message control parts but return to 
the process any data part in the message. 


1076 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


read() 


32588 In addition, read() and readv () fail if the STREAM head had processed an asynchronous error 

32589 before the call. In this case, the value of errno does not reflect the result of read( ) or readv( ), but 

32590 reflects the prior error. If a hangup occurs on the STREAM being read, read() continues to 

32591 operate normally until the STREAM head read queue is empty. Thereafter, it shall return 0. I 

32592 xsi The readv () function is equivalent to read(), but places the input data into the iovcnt buffers I 

32593 specified by the members of the iov array: iov[ 0], iov[ 1],..., iov[iovcnt-1]. The iovcnt argument is 

32594 valid if greater than 0 and less than or equal to {IOV_MAX}. 

32595 Each iovec entry specifies the base address and length of an area in memory where data should 

32596 be placed. The readv () function always fills an area completely before proceeding to the next. 

32597 Upon successful completion, readv () shall mark for update the st_atime field of the file. 

32598 sio If the CLDSYNC and 0_RSYNC bits have been set, read I/O operations on the file descriptor 

32599 complete as defined by synchronized I/O data integrity completion. If the 0_SYNC and 

32600 0_RSYNC bits have been set, read I/O operations on the file descriptor complete as defined by 

32601 synchronized I/O file integrity completion. 

32602 shm If fildes refers to a shared memory object, the result of the read() function is unspecified. 

32603 tym If fildes refers to a typed memory object, the result of the read () function is unspecified. I 

32604 MAN 

32605 

32606 XSI 

32607 

32608 

32609 

32610 


32611 RETURN VALUE 

32612 xsi Upon successful completion, read(), pread() and readv () shall return a non-negative integer 

32613 indicating the number of bytes actually read. Otherwise, the functions shall return -1 and set 

32614 errno to indicate the error. 

32615 ERRORS 

32616 xsi The read( ),pread() and readv( )functions shall fail if: 

32617 

32618 

[EAGAIN] 

The 0_NONBLOCK flag is set for the file descriptor and the process would be 
delayed. 

32619 

[EBADF] 

The fildes argument is not a valid file descriptor open for reading. 

32620 XSR 

32621 

[EBADMSG] 

The file is a STREAM file that is set to control-normal mode and the message 
waiting to be read includes a control part. 

32622 

32623 

[EINTR] 

The read operation was terminated due to the receipt of a signal, and no data 
was transferred. 

32624 XSR 

32625 

[EINVAL] 

The STREAM or multiplexer referenced by fildes is linked (directly or 
indirectly) downstream from a multiplexer. 

32626 XSI 

[EIO] 

A physical I/O error has occurred. 

32627 

32628 

32629 

32630 

[EIO] 

The process is a member of a background process attempting to read from its 
controlling terminal, the process is ignoring or blocking the SIGTTIN signal, 
or the process group is orphaned. This error may also be generated for 
implementation-dependent reasons. 


For regular files, no data transfer shall occur past the offset maximum established in the open 
file description associated with fildes. 

The pread() function performs the same action as read{), except that it reads from a given 
position in the file without changing the file pointer. The first three arguments to pread( ) are the 
same as read( ) with the addition of a fourth argument offset for the desired position inside the 
file. An attempt to perform a pread() on a file that is incapable of seeking results in an error. 

If fildes refers to a socket, read() is equivalent to recv( ) with no flags set. 
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32631 

32632 

32633 

32634 

32635 

32636 

32637 

32638 

32639 

32640 

32641 

32642 

32643 

32644 

32645 

32646 

32647 

32648 

32649 

32650 

32651 

32652 

32653 

32654 

32655 

32656 

32657 

32658 

32659 

32660 

32661 

32662 

32663 

32664 


xsi [EISDIR] The fildes argument refers to a directory and the implementation does not 

allow the directory to be read using read(), pread(), or readv(). The readdir() 
function should be used instead. 

man [EOVERFLOW] The file is a regular file, nbyte is greater than 0, the starting position is before 

the end-of-file, and the starting position is greater than or equal to the offset 
maximum established in the open file description associated with fildes. 

The readv( ) function shall fail if: 

man [EINVAL] The sum of the iovjen values in the iov array overflowed an ssize_t. 

xsi The read( ),pread( ) and readv( )functions may fail if: 

man [ENXIO] A request was made of a nonexistent device, or the request was outside the 

capabilities of the device. 

The readv( ) function may fail if: 

xsi [EINVAL] The iovcnt argument was less than or equal to 0, or greater than {IOV_MAX}. 

xsi The pread( ) function shall fail, and the file pointer shall remain unchanged, if: 
xsi [EINVAL] The offset argument is invalid. The value is negative. 

xsi [EOVERFLOW] The file is a regular file and an attempt was made to read or write at or beyond 

the offset maximum associated with the file. 

xsi [ENXIO] A request was outside the capabilities of the device. 

xsi [ESPIPE] fildes is associated with a pipe or FIFO. 

EXAMPLES 

Reading Data into a Buffer 

The following example reads data from the file associated with the file descriptor fd into the 
buffer pointed to by buf. 

#include <sys/types.h> 

#include <unistd.h> 

char buf[20] ; 
size_t nbytes; 
ssize_t bytes_read; 
int fd; 

nbytes = sizeof (buf); 

bytes_read = read (fd, buf, nbytes); 
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32666 

32667 

32668 

32669 

32670 

32671 

32672 

32673 

32674 

32675 

32676 

32677 

32678 

32679 

32680 

32681 

32682 

32683 

32684 

32685 

32686 

32687 

32688 

32689 

32690 

32691 

32692 

32693 

32694 

32695 

32696 

32697 

32698 

32699 

32700 

32701 

32702 

32703 

32704 

32705 

32706 

32707 

32708 

32709 

32710 


Reading Data into an Array 

The following example reads data from the file associated with the file descriptor fd into the 
buffers specified by members of the iov array. 

#include <sys/types.h> 

#include <sys/uio.h> 

#include <unistd.h> 

ssize_t bytes_read; 
int fd; 

char bufO [20]; 
char buf1 [30]; 
char buf2 [40]; 
int iovcnt; 
struct iovec iov[3]; 


iov[0] 

.iov_base 

= bufO; 


iov[0] 

.iov_len = 

sizeof 

(buf 0) ; 

iov[1] 

.iov_base 

= bufl; 


iov[1] 

.iov_len = 

sizeof 

(bufl); 

iov[2] 

.iov_base 

= buf2; 


iov[2] 

.iov_len = 

sizeof 

(buf 2) ; 

iovcnt 

= sizeof 

(iov) / 

sizeof (struct iovec); 

bytes_ 

read = readv (fd. 

iov, iovcnt); 


APPLICATION USAGE 

None. 

RATIONALE 

This volume of IEEE Std. 1003.1-200x does not specify the value of the file offset after an error is 
returned; there are too many cases. For programming errors, such as [EBADF], the concept is 
meaningless since no file is involved. For errors that are detected immediately, such as 
[EAGAIN], clearly the pointer should not change. After an interrupt or hardware error, however, 
an updated value would be very useful and is the behavior of many implementations. 

Note that a read() of zero bytes does not modify st_atime. A read () that requests more than zero 
bytes, but returns zero, shall modify s t_atime. I 

Implementations are allowed, but not required, to perform error checking for read () requests of I 
zero bytes. I 

Input and Output 

The use of I/O with large byte counts has always presented problems. Ideas such as tread () and 
hvrite () (using and returning longs) were considered at one time. The current solution is to use 
abstract types on the ISO C standard function to read () and write (). The abstract types can be 
declared so that existing functions work, but can also be declared so that larger types can be 
represented in future implementations. It is presumed that whatever constraints limit the 
maximum range of size_t also limit portable I/O requests to the same range. This volume of 
IEEE Std. 1003.1-200x also limits the range further by requiring that the byte count be limited so 
that a signed return value remains meaningful. Since the return type is also a (signed) abstract 
type, the byte count can be defined by the implementation to be larger than an int can hold. 
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32716 
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32719 
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32722 

32723 

32724 

32725 

32726 

32727 

32728 

32729 

32730 

32731 

32732 

32733 

32734 

32735 

32736 

32737 

32738 

32739 

32740 
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32752 

32753 

32754 

32755 

32756 
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32758 


The standard developers considered adding atomicity requirements to a pipe or FIFO, but I 
recognized that due to the nature of pipes and FIFOs there could be no guarantee of atomicity of I 

reads of {PIPE_BUF} or any other size that would be an aid to application portability. I 

This volume of IEEE Std. 1003.1-200x requires that no action be taken when nbyte is zero. This is I 

not intended to take precedence over detection of errors (such as invalid buffer pointers or file 
descriptors). This is consistent with the rest of this volume of IEEE Std. 1003.1-200x, but the 
phrasing here could be misread to require detection of the zero case before any other errors. A 
value of zero is to be considered a correct value, for which the semantics are a no-op. 

I/O is intended to be atomic to ordinary files and pipes and FIFOs. Atomic means that all the I 
bytes from a single operation that started out together end up together, without interleaving I 
from other I/O operations. It is a known attribute of terminals that this is not honored, and I 
terminals are explicitly (and implicitly permanently) excepted, making the behavior unspecified. I 
The behavior for other device types is also left unspecified, but the wording is intended to imply I 
that future standards might choose to specify atomicity (or not). I 

There were recommendations to add format parameters to read() and write () in order to handle I 
networked transfers among heterogeneous file system and base hardware types. Such a facility 
may be required for support by the OSI presentation of layer services. However, it was 
determined that this should correspond with similar C-language facilities, and that is beyond the 
scope of this volume of IEEE Std. 1003.1-200x. The concept was suggested to the developers of 
the ISO C standard for their consideration as a possible area for future work. 

In 4.3 BSD, a read( ) or write( ) that is interrupted by a signal before transferring any data does not 
by default return an [EINTR] error, but is restarted. In 4.2 BSD, 4.3 BSD, and the Eighth Edition, 
there is an additional function, select (), whose purpose is to pause until specified activity (data 
to read, space to write, and so on) is detected on specified file descriptors. It is common in 
applications written for those systems for select () to be used before read() in situations (such as 
keyboard input) where interruption of I/O due to a signal is desired. 

The issue of which files or file types are interruptible is considered an implementation design 
issue. This is often affected primarily by hardware and reliability issues. 

There are no references to actions taken following an "unrecoverable error". It is considered 
beyond the scope of this volume of IEEE Std. 1003.1-200x to describe what happens in the case of 
hardware errors. I 

Previous versions of IEEE Std. 1003.1-200x allowed two very different behaviors with regard to I 
the handling of interrupts. In order to minimize the resulting confusion, it was decided that I 
IEEE Std. 1003.1-200x should support only one of these behaviors. Historical practice on AT&T- I 
derived systems was to have read() and zvrite() return -1 and set errno to [EINTR] when I 
interrupted after some, but not all, of the data requested had been transferred. However, the U.S. I 
Department of Commerce FIPS 151-1 and FIPS 151-2 require the historical BSD behavior, in I 
which read( ) and ivrite( ) return the number of bytes actually transferred before the interrupt. If I 
-1 is returned when any data is transferred, it is difficult to recover from the error on a seekable I 
device and impossible on a non-seekable device. Most new implementations support this I 
behavior. The behavior required by IEEE Std. 1003.1-200x is to return the number of bytes I 
transferred. I 

IEEE Std. 1003.l-200x does not specify when an implementation that buffers read() s actually I 
moves the data into the user-supplied buffer, so an implementation may chose to do this at the I 
latest possible moment. Therefore, an interrupt arriving earlier may not cause read( ) to return a I 
partial byte count, but rather to return -1 and set errno to [EINTR], I 

Consideration was also given to combining the two previous options, and setting errno to I 
[EINTR] while returning a short count. However, not only is there no existing practice that I 
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32759 implements this, it is also contradictory to the idea that when errno is set, the function I 

32760 responsible shall return-1. I 

32761 FUTURE DIRECTIONS 

32762 None. 

32763 SEE ALSO 

32764 fcntl(), ioctl(), lseek(), open(), pipe(), the System Interface Definitions volume of 

32765 IEEE Std. 1003.1-200x, <stropts.h>, <sys/uio.h>, <unistd.h>, the System Interface Definitions I 

32766 volume of IEEE Std. 1003.1-200x, Chapter 11, General Terminal Interface I 

32767 CHANGE HISTORY 

32768 First released in Issue 1. 

32769 Derived from Issue 1 of the SVID. 

32770 Issue 4 

32771 The <unistd.h> header is added to the SYNOPSIS section. 

32772 The DESCRIPTION is rearranged for clarity and to align more closely with the ISO POSIX-1 

32773 standard. No functional changes are made other than as noted elsewhere in this CHANGE 

32774 HISTORY section. 

32775 In the ERRORS section in previous issues, generation of the [EIO] error depended on whether or 

32776 not an implementation supported Job Control. This functionality is now defined as mandatory. 

32777 The [ENXIO] error is marked as an extension. 

32778 The APPLICATION USAGE section is removed. 

32779 The description of [EINTR] is amended. 

32780 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

32781 • The type of the argument buf is changed from char* to void*, and the type of the argument 

32782 nbyte is changed from unsigned to size_t. 

32783 • The DESCRIPTION now states that the result is implementation-dependent if nbyte is greater 

32784 than {SSIZE_MAX}. This limit was defined by the constant {INT_MAX} in Issue 3. 

32785 The following change is incorporated for alignment with the FIPS requirements: 

32786 • The last paragraph of the DESCRIPTION now states that if read() is interrupted by a signal 

32787 after it has successfully read some data, it returns the number of bytes read. In Issue 3, it was 

32788 optional whether read() returned the number of bytes read, or whether it returned -1 with 

32789 errno set to [EINTR], 

32790 Issue 4, Version 2 

32791 The following changes are incorporated for X/OPEN UNIX conformance: 

32792 • The readv( ) function is added to the SYNOPSIS. 

32793 • The DESCRIPTION is updated to describe the reading of data from STREAMS files. An 

32794 operational description of the readv( ) function is also added. 

32795 • References to the readv() function are added to the RETURN VALUE and ERRORS sections 

32796 in appropriate places. 

32797 • The ERRORS section has been restructured to describe errors that apply generally (that is, to 

32798 both read() and readv ()), and to describe those that apply to readv() specifically. The 

32799 [EBADMSG], [EINVAL], and [EISDIR] errors are also added. 
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32801 

32802 

32803 

32804 

32805 

32806 

32807 

32808 

32809 

32810 

32811 

32812 

32813 

32814 

32815 

32816 

32817 

32818 

32819 

32820 

32821 

32822 

32823 

32824 

32825 


Issue 5 

The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 
Threads Extension. 

Large File Summit extensions are added. 

The pread() function is added. 

Issue 6 

The DESCRIPTION and ERRORS sections are updated so that references to STREAMS are I 
marked as part of the XSI STREAMS Option Group. I 

The following new requirements on POSIX implementations derive from alignment with the I 
Single UNIX Specification: 

• The DESCRIPTION now states that if read () is interrupted by a signal after it has successfully 
read some data, it returns the number of bytes read. In Issue 3, it was optional whether read() 
returned the number of bytes read, or whether it returned -1 with errno set to [EINTR], This 
is a FIPS requirement. 

• In the DESCRIPTION, text is added to indicate that for regular files, no data transfer occurs 
past the offset maximum established in the open file description associated with fildes. This 
change is to support large files. 

• The [EOVERFLOW] mandatory error condition is added. 

• The [ENXIO] optional error condition is added. 

Text referring to sockets is added to the DESCRIPTION. I 

The following changes were made to align with the IEEE PKXB.la draft standard: I 

• The effect of reading zero bytes is clarified. I 

The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that I 
read() results are unspecified for typed memory objects. I 

New RATIONALE is added to explain the atomicity requirements for input and output I 
operations. I 
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32826 NAME 

32827 read dir, readdir_r — read directory 

32828 SYNOPSIS 

32829 tinclude <dirent.h> 

32830 struct dirent *readdir(DIR *dirp); 

32831 TSF int readdir_r (DIR *dirp, struct dirent * entry, struct dirent ** result) ; 

32832 

32833 DESCRIPTION 

32834 The type DIR, which is defined in the header <dirent.h>, represents a directory stream, which is 

32835 an ordered sequence of all the directory entries in a particular directory. Directory entries 

32836 represent files; files may be removed from a directory or added to a directory asynchronously to 

32837 the operation of readdir (). 

32838 The readdir( ) function shall return a pointer to a structure representing the directory entry at the 

32839 current position in the directory stream specified by the argument dirp, and position the 

32840 directory stream at the next entry. It shall return a null pointer upon reaching the end of the 

32841 directory stream. The structure dirent defined by the <dirent.h> header describes a directory 

32842 entry. 

32843 The readdir{) function shall not return directory entries containing empty names. If entries for 

32844 dot or dot-dot exist, one entry shall be returned for dot and one entry shall be returned for dot- 

32845 dot; otherwise, they shall not be returned. 

32846 The pointer returned by readdir() points to data which may be overwritten by another call to 

32847 readdir() on the same directory stream. This data is not overwritten by another call to readdir() 

32848 on a different directory stream. 

32849 If a file is removed from or added to the directory after the most recent call to opendir () or 

32850 reivinddiri ), whether a subsequent call to readdir( ) returns an entry for that file is unspecified. 

32851 The readdir() function may buffer several directory entries per actual read operation; readdir() 

32852 shall mark for update the st_atime field of the directory each time the directory is actually read. 

32853 After a call to fork(), either the parent or child (but not both) may continue processing the 

32854 xsi directory stream using readdir( ), reiuinddir (), or seekdir( ). If both the parent and child processes 

32855 use these functions, the result is undefined. 

32856 man If the entry names a symbolic link, the value of the d_ino member is unspecified. 

32857 The readdir( ) function need not be reentrant. A function that is not required to be reentrant is not 

32858 required to be thread-safe. 

32859 tsf The readdir_r() function initializes the dirent structure referenced by entry to represent the 

32860 directory entry at the current position in the directory stream referred to by dirp, store a pointer 

32861 to this structure at the location referenced by result, and position the directory stream at the next 

32862 entry. 

32863 The storage pointed to by entry shall be large enough for a dirent with an array of char d_name 

32864 members containing at least |NAME_MAX} plus one elements. 

32865 Upon successful return, the pointer returned at *result shall have the same value as the argument I 

32866 entry. Upon reaching the end of the directory stream, this pointer shall have the value NULL. 

32867 The readdir_r( ) function shall not return directory entries containing empty names. 

32868 xsi If entries for dot or dot-dot exist, one entry is returned for dot and one entry is returned for dot- 

32869 dot; otherwise, they are not returned. 
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32870 tsf If a file is removed from or added to the directory after the most recent call to opendir() or 

32871 rewinddiri ), whether a subsequent call to readdir_r( ) returns an entry for that file is unspecified. 

32872 The readdir_r() function may buffer several directory entries per actual read operation; the 

32873 readdir_r() function shall mark for update the st_atime field of the directory each time the 

32874 directory is actually read. 

32875 Applications wishing to check for error situations should set errno to 0 before calling readdir( ). If 

32876 errno is set to non-zero on return, an error occurred. 

32877 RETURN VALUE 

32878 Upon successful completion, readdir{) shall return a pointer to an object of type struct dirent. 

32879 When an error is encountered, a null pointer shall be returned and errno shall be set to indicate 

32880 the error. When the end of the directory is encountered, a null pointer shall be returned and errno 

32881 is not changed. 

32882 tsf If successful, the readdir_r() function shall return zero; otherwise, an error number shall be 

32883 returned to indicate the error. 

32884 ERRORS 

32885 The readdir( ) function shall fail if: 

32886 man [EOVERFLOW] One of the values in the structure to be returned cannot be represented 

32887 correctly. 

32888 The readdir( ) function may fail if: 

32889 [EBADF] The dirp argument does not refer to an open directory stream. 

32890 man [ENOENT] The current position of the directory stream is invalid. 

32891 The readdir_r( ) function may fail if: 

32892 [EBADF] The dirp argument does not refer to an open directory stream. 

32893 EXAMPLES 

32894 The following sample code searches the current directory for the entry name: 

32895 dirp = opendir 

32896 while (dirp) { 

32897 errno = 0; 

32898 if ((dp = readdir (dirp) ) != NULL) { 

32899 if (strcmp (dp—>d_name, name) == 0) { 

32900 closedir (dirp) ; 

32901 return FOUND; 

32902 } 

32903 } else { 

32904 if (errno == 0) { 

32905 closedir (dirp) ; 

32906 return NOT_FOUND; 

32907 } 

32908 closedir (dirp) ; 

32909 return READ_ERROR; 


return OPEN_ERROR; 
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32913 

32914 

32915 

32916 

32917 

32918 

32919 

32920 

32921 

32922 

32923 

32924 

32925 

32926 

32927 

32928 

32929 

32930 

32931 

32932 

32933 

32934 

32935 

32936 

32937 

32938 

32939 

32940 

32941 

32942 

32943 

32944 

32945 

32946 

32947 

32948 

32949 

32950 

32951 

32952 

32953 


APPLICATION USAGE 

The readdir{) function should be used in conjunction with opendir (), closedir( ), and reivinddir( ) to 
examine the contents of the directory. 

The readdir_r() function is thread-safe and shall return values in a user-supplied buffer instead 
of possibly using a static data area that may be overwritten by each call. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

closedir(), lstat(), opendir(), rewinddir (), symlink (), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <dirent.h>, <sys/types.h> 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 
XSI-conformant systems. 

In the DESCRIPTION, the fact that XSI-conformant systems return entries for dot and dot-dot is 
marked as an extension. This functionality is not specified in the ISO POSIX-1 standard. 

There is some rewording of the DESCRIPTION and RETURN VALUE sections. No functional 
changes are made other than as noted elsewhere in this CHANGE HISTORY section. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The last paragraph of the DESCRIPTION describing a restriction after fork( ) is added. 

Issue 4, Version 2 

The following changes are incorporated for X/OPEN UNIX conformance: 

• A statement is added to the DESCRIPTION indicating the disposition of certain fields in 
struct dirent when an entry refers to a symbolic link. 

• The [ENOENT] optional error condition is added. 

Issue 5 

Large File Summit extensions are added. 

The readdir_r( ) function is included for alignment with the POSIX Threads Extension. 

A note indicating that the readdir( ) function need not be reentrant is added to the 
DESCRIPTION. 

Issue 6 

The readdir_r( ) function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS option. 

The Open Group corrigenda item U026/7 has been applied, correcting the prototype for 
readdir_r (). 

The Open Group corrigenda item U026/8 has been applied, clarifying the wording of the 
successful return for the readdir_r( ) function. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 
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32954 

32955 

32956 

32957 

32958 

32959 

32960 

32961 

32962 

32963 


• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• A statement is added to the DESCRIPTION indicating the disposition of certain fields in 
struct dirent when an entry refers to a symbolic link. 

• The [EOVERFLOW] mandatory error condition is added. This change is to support large 
files. 

• The [ENOENT] optional error condition is added. 

The APPLICATION USAGE section is updated to include a note on the thread-safe function and 
its avoidance of possibly using a static data area. 
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32964 NAME 

32965 readlink — read the contents of a symbolic link I 

32966 SYNOPSIS 

32967 #include <unistd.h> | 

32968 ssize_t readlink (const char *path, char *buf, size_t bufsize) ; I 

32969 DESCRIPTION I 

32970 The readlink () function shall place the contents of the symbolic link referred to by path in the 

32971 buffer bnf which has size bufsize. If the number of bytes in the symbolic link is less than bufsize, 

32972 the contents of the remainder of buf are unspecified. If the buf argument is not large enough to I 

32973 contain the link content, the first bufsize bytes shall be placed in buf. I 

32974 If the value of bufsize is greater than {SSIZE_MAX}, the result is implementation-dependent. 

32975 RETURN VALUE 

32976 Upon successful completion, readlink () shall return the count of bytes placed in the buffer. 

32977 Otherwise, it shall return a value of -1, leave the buffer unchanged, and set errno to indicate the 

32978 error. 


32979 ERRORS 

32980 The readlink () function shall fail if: 


32981 

32982 

32983 

32984 

32985 

32986 

32987 

32988 

32989 

32990 

32991 

32992 

32993 

32994 


[EACCES] 

[EINVAL] 

[EIO] 

[ENOENT] 

[ELOOP] 


Search permission is denied for a component of the path prefix of path. 

The path argument names a file that is not a symbolic link. 

An I/O error occurred while reading from the file system. 

A component of path does not name an existing file or path is an empty string. 

A loop exists in symbolic links encountered during resolution of the path 
argument. 


[ENAMETOOLONG] 

The length of path exceeds {PATH_MAX}, |NAME_MAX}. or a path name 
component is longer than 

[ENOTDIR] A component of the path prefix is not a directory. 

The readlink () function may fail if: 

[EACCES] Read permission is denied for the directory. 

[ELOOP] More than [SYMLOOP_MAX[ symbolic links were encountered during 

resolution of the path argument. 


32995 [ENAMETOOLONG] 

32996 As a result of encountering a symbolic link in resolution of the path argument, I 

32997 the length of the substituted path name string exceeded [PATH_MAX[. I 
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32998 EXAMPLES 

32999 Reading the Name of a Symbolic Link 

33000 The following example shows how to read the name of a symbolic link named /modules/passl. 

33001 #include <unistd.h> 

33002 char buf[1024]; 

33003 int len; 

33004 

33005 if ((len = readlink (" /modules/pass 1" , buf, sizeof (buf)-1) ) != -1); 

33006 buf [len] = ' \0'; 

33007 APPLICATION USAGE 

33008 Portable applications should not assume that the returned contents of the symbolic link are 

33009 null-terminated. 

33010 RATIONALE 

33011 Since IEEE Std. 1003.1-200x does not require any association of file times with symbolic links, I 

33012 there is no requirement that file times be updated by readlink (). The type associated with bufsiz I 

33013 is a size_t in order to be consistent with both the ISO C standard and the definition of read ( ). I 

33014 The behavior specified for readlink () when bufsiz is zero represents historical practice. For this I 

33015 case, the standard developers considered a change whereby readlink () would return the number I 

33016 of non-null bytes contained in the symbolic link with the buffer buf remaining unchanged; I 

33017 however, since the stat structure member st_size value can be used to determine the size of I 

33018 buffer necessary to contain the contents of the symbolic link as returned by readlink (), this I 

33019 proposal was rejected, and the historical practice retained. I 

33020 FUTURE DIRECTIONS 

33021 None. 

33022 SEE ALSO 

33023 lstat(), stat(), symlinki ), the System Interface Definitions volume of IEEE Std. 1003.l-200x, I 

33024 <unistd.h> 

33025 CHANGE HISTORY 

33026 First released in Issue 4, Version 2. 

33027 Issue 5 

33028 Moved from X/OPEN UNIX extension to BASE. 

33029 Issue 6 

33030 The return type is changed to ssize_t, to align with the IEEE P1003.1a draft standard. I 

33031 The following new requirements on POSIX implementations derive from alignment with the 

33032 Single UNIX Specification: 

33033 • This function is made mandatory. I 

33034 • In this function it is possible for the return value to exceed the range of the type ssize_t (since I 

33035 size_t has a larger range of positive values than ssize_t). A sentence restricting the size of 

33036 the size_t object is added to the description to resolve this conflict. 

33037 The following changes are made for alignment with the ISO POSIX-1:1996 standard: I 

33038 • The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 

33039 This is since behavior may vary from one file system to another. 
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33040 

33041 

33042 


• The FUTURE DIRECTIONS section is changed to None. 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• The [ELOOP] optional error condition is added. 


System Interfaces, Issue 6 


1089 



readv() 


System Interfaces 


33043 NAME 

33044 readv — vectored read from file 

33045 SYNOPSIS 

33046 xsi #include <sys/uio.h> 

33047 ssize_t readv (int fildes, const struct iovec *iov, int iovcnt) ; 

33048 

33049 DESCRIPTION 

33050 Refer to read (). 
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33051 

33052 

33053 

33054 

33055 

33056 

33057 

33058 

33059 

33060 

33061 

33062 

33063 

33064 

33065 

33066 

33067 

33068 

33069 

33070 

33071 

33072 

33073 

33074 

33075 

33076 

33077 

33078 

33079 

33080 

33081 

33082 

33083 

33084 

33085 

33086 

33087 

33088 

33089 

33090 

33091 

33092 

33093 


NAME 

realloc — memory reallocator 

SYNOPSIS 

#include <stdlib.h> 

void *realloc(void *ptr, size_t size); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The realloc() function shall change the size of the memory object pointed to by ptr to the size 
specified by size. The contents of the object shall remain unchanged up to the lesser of the new 
and old sizes. If the new size of the memory object would require movement of the object, the 
space for the previous instantiation of the object is freed. If the new size is larger, the contents of 
the newly allocated portion of the object are unspecified. If size is 0 and ptr is not a null pointer, 
the object pointed to is freed. If the space cannot be allocated, the object remains unchanged. 

If ptr is a null pointer, reallocO shall behave like malloc( ) for the specified size. 

If ptr does not match a pointer returned earlier by calloc ( ), malloc (), or realloc () or if the space has 
previously been deallocated by a call to free( ) or realloc (), the behavior is undefined. 

cx The order and contiguity of storage allocated by successive calls to reallocO is unspecified. The 
pointer returned if the allocation succeeds is suitably aligned so that it may be assigned to a 
pointer to any type of object and then used to access such an object in the space allocated (until 
the space is explicitly freed or reallocated). Each such allocation shall yield a pointer to an object 
disjoint from any other object. The pointer returned points to the start (lowest byte address) of 
the allocated space. If the space cannot be allocated, a null pointer shall be returned. 

RETURN VALUE 

Upon successful completion with a size not equal to 0, reallocO shall return a pointer to the 
(possibly moved) allocated space. If size is 0, either a null pointer or a unique pointer that can be 
successfully passed to free( ) shall be returned. If there is not enough available memory, reallocO 
cx shall return a null pointer and set errno to [ENOMEM]. 

ERRORS 

The realloc () function shall fail if: 
cx [ENOMEM] Insufficient memory is available. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

calloc (), free (), malloc ( ), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

<stdlib.h> 
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33094 

33095 

33096 

33097 

33098 

33099 

33100 

33101 

33102 

33103 

33104 

33105 

33106 

33107 

33108 

33109 

33110 

33111 

33112 

33113 


CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The setting of errno and the [ENOMEM] error are marked as extensions. 

The APPLICATION USAGE section is removed. 

The following changes are incorporated for alignment with the ISO C standard: 

• The DESCRIPTION is updated to indicate as follows: 

— The order and contiguity of storage allocated by successive calls to this function is 
unspecified. 

— Each allocation yields a pointer to an object disjoint from any other object. 

— The returned pointer points to the lowest byte address of the allocation. 

• The RETURN VALUE section is updated to indicate what is returned if size is 0. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the RETURN VALUE section, if there is not enough available memory, the setting of errno 
to [ENOMEM] is added. 

• The [ENOMEM] error condition is added. 


1092 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


realpath() 


33114 NAME 

33115 realpath — resolve a path name 

33116 Notes to Reviewers 

33117 This section with side shading will not appear in the final copy. - Ed. 

33118 This function or these functions are recommended to become mandatory parts of POSIX.l in the 

33119 next draft. 

33120 SYNOPSIS 

33121 xsi tinclude <stdlib.h> 

33122 char *realpath(const char *file_name, char * resolved_name) ; 

33123 

33124 DESCRIPTION 

33125 The realpath () function derives, from the path name pointed to by file_name , an absolute path 

33126 name that names the same file, whose resolution does not involve , or symbolic links. 

33127 The generated path name is stored as a null-terminated string, up to a maximum of 

33128 {PATH_MAX} bytes, in the buffer pointed to by resolved_name. 

33129 RETURN VALUE 

33130 Upon successful completion, realpath () shall return a pointer to the resolved name. Otherwise, I 

33131 realpath () shall return a null pointer and set errno to indicate the error, and the contents of the 

33132 buffer pointed to by resolved_name are undefined. 

33133 ERRORS 

33134 The realpath () function shall fail if: 

33135 [EACCES] Read or search permission was denied for a component otfile_name. 

33136 [EINVAL] Either the file_name or resolved_name argument is a null pointer. 

33137 [EIO] An error occurred while reading from the file system. 

33138 [ELOOP] Too many symbolic links were encountered in resolving path. 

33139 [ENAMETOOLONG] 

33140 The file_name argument is longer than |PATH_MAX} or a path name I 

33141 component is longer than [NAME_MAX[ while _POSIX_NO_TRUNC is in 

33142 effect. 

33143 [ENOENT] A component ot file_name does not name an existing file or file_name points to 

33144 an empty string. 

33145 [ENOTDIR] A component of the path prefix is not a directory. 

33146 The realpath () function may fail if: 

33147 [ENAMETOOLONG] 

33148 Path name resolution of a symbolic link produced an intermediate result 

33149 whose length exceeds |PATH_MAX}. 

33150 [ENOMEM] Insufficient storage space is available. 
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33151 EXAMPLES 

33152 Generating an Absolute Path Name 

33153 The following example generates an absolute path name for the file identified by the symlinkpath 

33154 argument. The generated path name is stored in the actualpath array. 

33155 #include <stdlib.h> 

33156 

33157 char *symlinkpath = "/tmp/symlink/f ile" ; 

33158 char actualpath [PATH_MAX+1 ] ; 

33159 char *ptr; 

33160 ptr = realpath (symlinkpath, actualpath); 

33161 APPLICATION USAGE 

33162 None. 

33163 RATIONALE 

33164 None. 

33165 FUTURE DIRECTIONS 

33166 None. 

33167 SEE ALSO 

33168 getcivd (), sysconf( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

33169 CHANGE HISTORY 

33170 First released in Issue 4, Version 2. 

33171 Issue 5 

33172 Moved from X/OPEN UNIX extension to BASE. 

33173 Issue 6 

33174 The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. This I 

33175 is since behavior may vary from one file system to another. 
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33176 NAME 

33177 recv — receive a message from a connected socket 

33178 SYNOPSIS 

33179 tinclude <sys/socket. h> 


33180 ssize_t recv(int socket, void * buffer, size_t length, int flags)} 


33181 DESCRIPTION 

33182 The recv () function receives a message from a connection-mode or connectionless-mode socket. 

33183 It is normally used with connected sockets because it does not permit the application to retrieve 

33184 the source address of received data. 


33185 The recv() function takes the following arguments: 


33186 

33187 

33188 

33189 

33190 


socket Specifies the socket file descriptor. 

buffer Points to a buffer where the message should be stored. 

length Specifies the length in bytes of the buffer pointed to by the buffer argument. 

flags Specifies the type of message reception. Values of this argument are formed by 

logically OR'ing zero or more of the following values: 


33191 

33192 


MSG_PEEK Peeks at an incoming message. The data is treated as unread and 
the next recv () or similar function shall still return this data. 


33193 

33194 


MSG_OOB Requests out-of-band data. The significance and semantics of 
out-of-band data are protocol-specific. 


33195 

33196 

33197 

33198 

33199 


MSG_WAITALL Requests that the function block until the full amount of data 
requested can be returned. The function may return a smaller 
amount of data if a signal is caught, if the connection is 
terminated, if MSG_PEEK was specified, or if an error is pending 
for the socket. 


33200 The recv () function shall return the length of the message written to the buffer pointed to by the 

33201 buffer argument. For message-based sockets, such as SOCK_DGRAM and SOCK_SEQPACKET, 

33202 the entire message shall be read in a single operation. If a message is too long to fit in the 

33203 supplied buffer, and MSG_PEEK is not set in the flags argument, the excess bytes shall be 

33204 discarded. For stream-based sockets, such as SOCK_STREAM, message boundaries shall be 

33205 ignored. In this case, data is returned to the user as soon as it becomes available, and no data 

33206 shall be discarded. 


33207 If the MSG_WAITALL flag is not set, data shall be returned only up to the end of the first 

33208 message. 

33209 If no messages are available at the socket and 0_NONBLOCK is not set on the socket's file 

33210 descriptor, recv () shall block until a message arrives. If no messages are available at the socket 

33211 and CLNONBLOCK is set on the socket's file descriptor, recv() shall fail and set errno to 

33212 [EAGAIN] or [EWOULDBLOCK]. 


33213 RETURN VALUE 

33214 Upon successful completion, recv() shall return the length of the message in bytes. If no 

33215 messages are available to be received and the peer has performed an orderly shutdown, recv () 

33216 shall return 0. Otherwise, -1 shall be returned and errno set to indicate the error. 


System Interfaces, Issue 6 


1095 




recv() 


System Interfaces 


33217 ERRORS 

33218 The recv () function shall fail if: 


33219 

33220 

33221 

33222 

33223 


[EAGAIN] or [EWOULDBLOCK] 

The socket's file descriptor is marked 0_N0NBL0CK and no data is waiting 
to be received; or MSG_OOB is set and no out-of-band data is available and 
either the socket's file descriptor is marked 0_N0NBL0CK or the socket does 
not support blocking to await out-of-band data. 


33224 

33225 

33226 

33227 

33228 


[EBADF] 

[ECONNRESET] 

[EFAULT] 

[EINTR] 


The socket argument is not a valid file descriptor. 

A connection was forcibly closed by a peer. 

The buffer parameter cannot be accessed or written. 

The recv() function was interrupted by a signal that was caught, before any 
data was available. 


33229 

33230 

33231 

33232 

33233 

33234 


[EINVAL] 

[ENOTCONN] 

[ENOTSOCK] 

[EOPNOTSUPP] 

[ETIMEDOUT] 


The MSG_OOB flag is set and no out-of-band data is available. 

A receive is attempted on a connection-mode socket that is not connected. 

The socket argument does not refer to a socket. 

The specified flags are not supported for this socket type or protocol. 

The connection timed out during connection establishment, or due to a 
transmission timeout on active connection. 


33235 The recv() function may fail if: 

33236 [EIO] An I/O error occurred while reading from or writing to the file system. 

33237 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 

33238 [ENOMEM] Insufficient memory was available to fulfill the request. 

33239 xsr [ENOSR] There were insufficient STREAMS resources available for the operation to 

33240 complete. 

33241 EXAMPLES 

33242 None. 

33243 APPLICATION USAGE 

33244 The recv( ) function is identical to recvfrom () 

33245 flags are used. 

33246 The select () and poll () functions can be used 

33247 RATIONALE 

33248 None. 

33249 FUTURE DIRECTIONS 

33250 None. 

33251 SEE ALSO 

33252 poll{), read(), recvmsg (), recvfrom{), select (), send(), sendmsg{), sendto{), shutdown(), socket{), 

33253 ivrite( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <sys/socket.h> 

33254 CHANGE HISTORY 

33255 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 


with a zero address Jen argument, and to read () if no 
to determine when data is available to be received. 
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33256 NAME 

33257 recvfrom — receive a message from a socket 

33258 SYNOPSIS 

33259 tinclude <sys/socket. h> 

33260 ssize_t recvfrom (int socket, void *buffer, size_t length, int flags, 

33261 struct sockaddr * address, socklen_t * address_len) ; 

33262 DESCRIPTION 

33263 The recvfrom () function receives a message from a connection-mode or connectionless-mode 

33264 socket. It is normally used with connectionless-mode sockets because it permits the application 

33265 to retrieve the source address of received data. 

33266 The recvfrom () function takes the following arguments: 

33267 socket Specifies the socket file descriptor. 

33268 buffer Points to the buffer where the message should be stored. 

33269 length Specifies the length in bytes of the buffer pointed to by the buffer argument. 

33270 flags Specifies the type of message reception. Values of this argument are formed 

33271 by logically OR'ing zero or more of the following values: 

33272 MSG_PEEK Peeks at an incoming message. The data is treated as unread 

33273 and the next recvfrom () or similar function shall still return 

33274 this data. 


33275 

33276 

33277 

33278 

33279 

33280 

33281 

33282 

33283 

33284 

33285 

33286 


MSG_OOB Requests out-of-band data. The significance and semantics 
of out-of-band data are protocol-specific. 

MSG_WAITALL Requests that the function block until the full amount of 
data requested can be returned. The function may return a 
smaller amount of data if a signal is caught, if the 
connection is terminated, if MSG_PEEK was specified, or if 
an error is pending for the socket. 

address A null pointer, or points to a sockaddr structure in which the sending address 

is to be stored. The length and format of the address depend on the address 
family of the socket. 

addressjen Specifies the length of the sockaddr structure pointed to by the address 

argument. 


33287 The recvfrom () function shall return the length of the message written to the buffer pointed to by 

33288 the buffer argument. For message-based sockets, such as SOCK_DGRAM and 

33289 SOCK_SEQPACKET, the entire message shall be read in a single operation. If a message is too 

33290 l° n g to fit in the supplied buffer, and MSG_PEEK is not set in the flags argument, the excess 

33291 bytes shall be discarded. For stream-based sockets, such as SOCK_STREAM, message 

33292 boundaries shall be ignored. In this case, data is returned to the user as soon as it becomes 

33293 available, and no data shall be discarded. 


33294 If the MSG_WAITALL flag is not set, data shall be returned only up to the end of the first 

33295 message. 

33296 Not all protocols provide the source address for messages. If the address argument is not a null 

33297 pointer and the protocol provides the source address of messages, the source address of the 

33298 received message is stored in the sockaddr structure pointed to by the address argument, and the 

33299 length of this address is stored in the object pointed to by the addressjen argument. 
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33300 

33301 

33302 

33303 

33304 

33305 

33306 

33307 

33308 

33309 

33310 

33311 

33312 

33313 

33314 

33315 

33316 

33317 

33318 

33319 

33320 

33321 

33322 

33323 

33324 

33325 

33326 

33327 

33328 

33329 

33330 

33331 

33332 

33333 

33334 

33335 


If the actual length of the address is greater than the length of the supplied sockaddr structure, 
the stored address shall be truncated. 

If the address argument is not a null pointer and the protocol does not provide the source address 
of messages, the value stored in the object pointed to by address is unspecified. 

If no messages are available at the socket and 0_NONBLOCK is not set on the socket's file 
descriptor, recvfrom() blocks until a message arrives. If no messages are available at the socket 
and 0_NONBLOCK is set on the socket's file descriptor, recvfrom () shall fail and set errno to 
[E AG AIN] or [EW OULDBLOCK]. 

RETURN VALUE 

Upon successful completion, recvfrom () shall return the length of the message in bytes. If no 
messages are available to be received and the peer has performed an orderly shutdown, 
recvfrom( ) shall return 0. Otherwise, the function shall return -1 and set errno to indicate the 
error. 

ERRORS 

The recvfrom () function shall fail if: 

[EAGAIN] or [EWOULDBLOCK] 

The socket's file descriptor is marked 0_NONBLOCK and no data is waiting 
to be received; or MSG_OOB is set and no out-of-band data is available and 
either the socket's file descriptor is marked 0_NONBLOCK or the socket does 
not support blocking to await out-of-band data. 

The socket argument is not a valid file descriptor. 

A connection was forcibly closed by a peer. 

The buffer, address, or address Jen parameter cannot be accessed or written. 

A signal interrupted recvfrom () before any data was available. 

The MSG_OOB flag is set and no out-of-band data is available. 

A receive is attempted on a connection-mode socket that is not connected. 

The socket argument does not refer to a socket. 

The specified flags are not supported for this socket type. 

The connection timed out during connection establishment, or due to a 
transmission timeout on active connection. 

The recvfrom () function may fail if: 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[ENOBUFS] Insufficient resources were available in the system to perform the operation. 

[ENOMEM] Insufficient memory was available to fulfill the request. 

xsr [ENOSR] There were insufficient STREAMS resources available for the operation to 

complete. 


[EBADF] 

[ECONNRESET] 

[EFAULT] 

[EINTR] 

[EINVAL] 

[ENOTCONN] 

[ENOTSOCK] 

[EOPNOTSUPP] 

[ETIMEDOUT] 
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33336 EXAMPLES 

33337 None. 

33338 APPLICATION USAGE 

33339 The select () and poll () functions can be used to determine when data is available to be received. 

33340 RATIONALE 

33341 None. 

33342 FUTURE DIRECTIONS 

33343 None. 

33344 SEE ALSO 

33345 poll (), read(), recv{), recvmsg(), select () on page 11441 send(), sendmsg(), sendto(), shutdown(), 

33346 socket (), write(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

33347 <sys/socket.h> 

33348 CHANGE HISTORY 

33349 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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33350 NAME 

33351 recvmsg — receive a message from a socket 

33352 SYNOPSIS 

33353 tinclude <sys/socket. h> 


33354 ssize_t recvmsg (int socket, struct msghdr *message, int flags); 


33355 DESCRIPTION 

33356 The recvmsgO function receives a message from a connection-mode or connectionless-mode 

33357 socket. It is normally used with connectionless-mode sockets because it permits the application 

33358 to retrieve the source address of received data. 


33359 The recvmsg( ) function takes the following arguments: 


33360 socket 


Specifies the socket file descriptor. 


33361 message 

33362 

33363 

33364 


Points to a msghdr structure, containing both the buffer to store the source 
address and the buffers for the incoming message. The length and format of 
the address depend on the address family of the socket. The msg_flags member 
is ignored on input, but may contain meaningful values on output. 


33365 flags Specifies the type of message reception. Values of this argument are formed 

33366 by logically OR'ing zero or more of the following values: 


33367 

33368 


MSG_OOB Requests out-of-band data. The significance and semantics 
of out-of-band data are protocol-specific. 


33369 

33370 

33371 

33372 

33373 

33374 


MSG_PEEK Peeks at the incoming message. 

MSG_WAITALL Requests that the function block until the full amount of 
data requested can be returned. The function may return a 
smaller amount of data if a signal is caught, if the 
connection is terminated, if MSG_PEEK was specified, or if 
an error is pending for the socket. 


33375 The recvmsg () function receives messages from unconnected or connected sockets and shall 

33376 return the length of the message. 


33377 The recvmsg( ) function shall return the total length of the message. For message-based sockets, 

33378 such as SOCK_DGRAM and SOCK_SEQPACKET, the entire message shall be read in a single 

33379 operation. If a message is too long to fit in the supplied buffers, and MSG_PEEK is not set in the 

33380 flags argument, the excess bytes shall be discarded, and MSG_TRUNC is set in the msgjtags 

33381 member of the msghdr structure. For stream-based sockets, such as SOCK_STREAM, message 

33382 boundaries shall be ignored. In this case, data is returned to the user as soon as it becomes 

33383 available, and no data shall be discarded. 


33384 If the MSG_WAITALL flag is not set, data shall be returned only up to the end of the first 

33385 message. 

33386 If no messages are available at the socket and 0_N0NBL0CK is not set on the socket's file 

33387 descriptor, recvfromO shall block until a message arrives. If no messages are available at the 

33388 socket and 0_N0NBL0CK is set on the socket's file descriptor, recvfromO function shall fail and 

33389 set errno to [EAGAIN] or [EWOULDBLOCK]. 

33390 In the msghdr structure, the msg_name and msg_namelen members specify the source address if 

33391 the socket is unconnected. If the socket is connected, the msg_name and msg_namelen members 

33392 are ignored. The msg_name member may be a null pointer if no names are desired or required. 

33393 The msg_iov and msg_iovlen fields are used to specify where the received data shall be stored. 

33394 msg_iov points to an array of iovec structures; msg_iovlen shall be set to the dimension of this 
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33395 

33396 

33397 

33398 

33399 

33400 

33401 

33402 

33403 

33404 

33405 

33406 

33407 

33408 

33409 

33410 

33411 

33412 

33413 

33414 

33415 

33416 

33417 

33418 

33419 

33420 

33421 

33422 

33423 

33424 

33425 

33426 

33427 

33428 

33429 

33430 

33431 

33432 

33433 

33434 


array. In each iovec structure, the iovjbase field specifies a storage area and the iovjen field gives 
its size in bytes. Each storage area indicated by msg_iov is filled with received data in turn until 
all of the received data is stored or all of the areas have been filled. 

Upon successful completion, the msg_flags member of the message header is the bitwise- 
inclusive OR of all of the following flags that indicate conditions detected for the received 
message: 

MSG_EOR End of record was received (if supported by the protocol). 

MSG_OOB Out-of-band data was received. 

MSG_TRUNC Normal data was truncated. 

MSG_CTRUNC Control data was truncated. 

RETURN VALUE 

Upon successful completion, recvmsg( ) shall return the length of the message in bytes. If no 
messages are available to be received and the peer has performed an orderly shutdown, 
recvmsg( ) shall return 0. Otherwise, -1 shall be returned and errno set to indicate the error. 

ERRORS 

The recvmsg( ) function shall fail if: 

[EAGAIN] or [EWOULDBLOCK] 

The socket's file descriptor is marked 0_NONBLOCK and no data is waiting 
to be received; or MSG_OOB is set and no out-of-band data is available and 
either the socket's file descriptor is marked 0_NONBLOCK or the socket does 
not support blocking to await out-of-band data. 

The socket argument is not a valid open file descriptor. 

A connection was forcibly closed by a peer. 

The message parameter, or storage pointed to by the msg_name, msg_control , or 
msg_iov fields of the message parameter, or storage pointed to by the iovec 
structures pointed to by the msg_iov field cannot be accessed or written. 

This function was interrupted by a signal before any data was available. 

The sum of the iovjen values overflows a ssize_t, or the MSG_OOB flag is set 
and no out-of-band data is available. 

The msgjovlen member of the msghdr structure pointed to by message is less 
than or equal to 0, or is greater than {IOV_MAX}. 

A receive is attempted on a connection-mode socket that is not connected. 

The socket argument does not refer to a socket. 

The specified flags are not supported for this socket type. 

The connection timed out during connection establishment, or due to a 
transmission timeout on active connection. 

The recvmsg( ) function may fail if: 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[ENOBUFS] Insufficient resources were available in the system to perform the operation. 
[ENOMEM] Insufficient memory was available to fulfill the request. 


[EBADF] 

[ECONNRESET] 

[EFAULT] 

[EINTR] 

[EINVAL] 

[EMSGSIZE] 

[ENOTCONN] 

[ENOTSOCK] 

[EOPNOTSUPP] 

[ETIMEDOUT] 
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33435 xsr [ENOSR] There were insufficient STREAMS resources available for the operation to 

33436 complete. 

33437 EXAMPLES 

33438 None. 

33439 APPLICATION USAGE 

33440 The select () and poll ( ) functions can be used to determine when data is available to be received. 

33441 RATIONALE 

33442 None. 

33443 FUTURE DIRECTIONS 

33444 None. 

33445 SEE ALSO 

33446 poll (), recv{), recvfrom(), select(), send{), sendmsg(), sendto(), shutdown(), socket (), the System 

33447 Interface Definitions volume of IEEE Std. 1003.1-200x, <sys/socket.h> 

33448 CHANGE HISTORY 

33449 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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33450 NAME 

33451 regcomp, regerror, regexec, regfree — regular expression matching 

33452 SYNOPSIS 

33453 #include <regex.h> 

33454 int regcomp (regex_t *preg, const char * pattern, int cflags) ; 

33455 size_t regerror (int errcode, const regex_t *preg, 

33456 char *errbuf, size_t errbuf_size) ; 

33457 int regexec (const regex_t *preg, const char * string, 

33458 size_t nmatch, regmatch_t pmatch[] , int eflags) ; 

33459 void regfree (regex_t *preg) ; 

33460 DESCRIPTION 

33461 These functions interpret basic and extended regular expressions as described in the System I 

33462 Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 9, Regular Expressions. I 

33463 The regex_t structure contains at least the following member: 

33464 

33465 

33466 


33467 The regmatch_t structure contains at least the following members: 

33468 

33469 

33470 

33471 

33472 


Member Type 

Member Name 

Description 

regoff_t 

regoff_t 

rm_so 

rm_eo 

Byte offset from start of string to start of substring. 
Byte offset from start of string of the first character 
after the end of substring. 


Member Type 

Member Name 

Description 

siz e_t 

re_nsub 

Number of parenthesized subexpressions. 


33473 The regcomp () function shall compile the regular expression contained in the string pointed to by 

33474 the pattern argument and places the results in the structure pointed to by preg. The cflags 

33475 argument is the bitwise-inclusive OR of zero or more of the following flags, which are defined in 

33476 the header <regex.h>: 


33477 

33478 

33479 

33480 

33481 


REG_EXTENDED 

REGJCASE 

REG_NOSUB 

REG_NEWLINE 


Use Extended Regular Expressions. 

Ignore case in match. (See the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Chapter 9, Regular Expressions.) I 

Report only success/fail in regexec (). 

Change the handling of <newline> characters, as described in the text. 


33482 The default regular expression type for pattern is a Basic Regular Expression. The application can 

33483 specify Extended Regular Expressions using the REG_EXTENDED cflags flag. 

33484 If the REG_NOSUB flag was not set in cflags, then regcomp () shall set re_nsnb to the number of 

33485 parenthesized subexpressions (delimited by " \ (\) " in basic regular expressions or " ( ) " in 

33486 extended regular expressions) found in pattern. 


33487 The regexec () function compares the null-terminated string specified by string with the compiled 

33488 regular expression preg initialized by a previous call to regcomp (). If it finds a match, regexec () 

33489 shall return 0; otherwise, it shall return non-zero indicating either no match or an error. The 

33490 eflags argument is the bitwise-inclusive OR of zero or more of the following flags, which are 

33491 defined in the header <regex.h>: 
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33492 

33493 

33494 

33495 

33496 

33497 

33498 

33499 

33500 

33501 

33502 

33503 

33504 

33505 

33506 

33507 

33508 

33509 

33510 

33511 

33512 

33513 

33514 

33515 

33516 

33517 

33518 

33519 

33520 

33521 

33522 

33523 

33524 

33525 

33526 

33527 

33528 

33529 

33530 


REG_NOTBOL The first character of the string pointed to by string is not the beginning of the 
line. Therefore, the circumflex character (' ''), when taken as a special 
character, shall not match the beginning of string. 

REG_NOTEOL The last character of the string pointed to by string is not the end of the line. 

Therefore, the dollar sign (' $'), when taken as a special character, shall not 
match the end of string. 

If nmatch is 0 or REG_NOSUB was set in the cflags argument to regcompO, then regexecO shall 
ignore the pmatch argument. Otherwise, the application shall ensure that the pmatch argument I 
points to an array with at least nmatch elements, and regexec( ) shall fill in the elements of that I 
array with offsets of the substrings of string that correspond to the parenthesized subexpressions 
of pattern : pmatch[i].rm_so shall be the byte offset of the beginning and pmatch[i].rm_eo shall be I 
one greater than the byte offset of the end of substring i. (Subexpression i begins at the zth I 
matched open parenthesis, counting from 1.) Offsets in pmatch[ 0] identify the substring that 
corresponds to the entire regular expression. Unused elements of pmatch up to pmatch [nmatch- 1] I 
shall be filled with -1. If there are more than nmatch subexpressions in pattern ( pattern itself I 
counts as a subexpression), then regexec( ) shall still do the match, but shall record only the first 
nmatch substrings. 

When matching a basic or extended regular expression, any given parenthesized subexpression 
of pattern might participate in the match of several different substrings of string, or it might not 
match any substring even though the pattern as a whole did match. The following rules are used 
to determine which substrings to report in pmatch when matching regular expressions: 

1. If subexpression i in a regular expression is not contained within another subexpression, 

and it participated in the match several times, then the byte offsets in pmatch[i] shall I 
delimit the last such match. I 

2. If subexpression i is not contained within another subexpression, and it did not participate 

in an otherwise successful match, the byte offsets in pmatch[i] shall be -1. A subexpression I 
does not participate in the match when: I 

' *' or " \ {\}" appears immediately after the subexpression in a basic regular 
expression, or ' *', ' ?', or " { }" appears immediately after the subexpression in an 
extended regular expression, and the subexpression did not match (matched 0 times) 

or: 

' | ' is used in an extended regular expression to select this subexpression or another, 
and the other subexpression matched. 

3. If subexpression i is contained within another subexpression /, and i is not contained 

within any other subexpression that is contained within;, and a match of subexpression; I 
is reported in pmatch[j], then the match or non-match of subexpression i reported in I 
pmatch [i ] shall be as described in 1. and 2. above, but within the substring reported in I 
pmatch[j] rather than the whole string. The offsets in pmatch[i] are still relative to the start I 
of string. I 
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33531 Notes to Reviewers 

33532 This section with side shading will not appear in the final copy. - Ed. 

33533 Dl, XSH, ERN 283 proposes changing "but within" above to "but describing the substring 

33534 found within the substring reported in pmatch[j] rather than the whole string. The byte 

33535 offsets are relative to the whole string." 

33536 4. If subexpression i is contained in subexpression;, and the byte offsets in pmatch[j] are —1, I 

33537 then the pointers in pmatch [i ] shall also be -1. I 

33538 5. If subexpression i matched a zero-length string, then both byte offsets in pmatch [/'] shall be I 

33539 the byte offset of the character or null terminator immediately following the zero-length I 

33540 string. I 

33541 If, when regexec () is called, the locale is different from when the regular expression was 

33542 compiled, the result is undefined. 

33543 If REG_NEWLINE is not set in cflags, then a <newline> character in pattern or string shall be 

33544 treated as an ordinary character. If REG_NEWLINE is set, then <newline> shall be treated as an 

33545 ordinary character except as follows: 

33546 1. A <newline> character in string shall not be matched by a period outside a bracket I 

33547 expression or by any form of a non-matching list (see the System Interface Definitions I 

33548 volume of IEEE Std. 1003.1-200x, Chapter 9, Regular Expressions). I 

33549 2. A circumflex ('"') in pattern, when used to specify expression anchoring (see the System I 

33550 Interface Definitions volume of IEEE Std. 1003.1-200x, Section 9.3.8, BRE Expression I 

33551 Anchoring), shall match the zero-length string immediately after a <newline> in string , I 

33552 regardless of the setting of REG_NOTBOL. 

33553 3. A dollar sign (' $') in pattern, when used to specify expression anchoring, shall match the I 

33554 zero-length string immediately before a <newline> in string, regardless of the setting of 

33555 REG_N OTEOL. 

33556 The regfree( ) function frees any memory allocated by regcomp () associated with preg. 

33557 The following constants are defined as error return values: 

33558 REG_NOMATCH regexec () failed to match. 

33559 REG_BADPAT Invalid regular expression. 

33560 REG_ECOLLATE Invalid collating element referenced. 

33561 REG_ECTYPE Invalid character class type referenced. 

33562 REG_EESCAPE Trailing ' \' in pattern. 

33563 REG_ESUBREG Number in "\digit" invalid or in error. 

33564 REG_EBRACK " [ ] " imbalance. 

33565 REG_ENOSYS The function is not supported. 

33566 REG_EPAREN " \ (\) " or " () " imbalance. 

33567 REG_EBRACE " \ { \ }" imbalance. 

33568 REG_BADBR Content of " \ { \ }" invalid: not a number, number too large, more than 

33569 two numbers, first larger than second. 

33570 REG_ERANGE Invalid endpoint in range expression. 
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33571 

33572 

33573 

33574 

33575 

33576 

33577 

33578 

33579 

33580 

33581 

33582 

33583 

33584 

33585 

33586 

33587 

33588 

33589 

33590 

33591 

33592 

33593 

33594 

33595 

33596 

33597 

33598 

33599 

33600 

33601 

33602 

33603 

33604 

33605 

33606 

33607 

33608 

33609 

33610 

33611 

33612 

33613 

33614 


REG_ESPACE Out of memory. 

REG_BADRPT , or ' +' not preceded by valid regular expression. 

The regerror() function provides a mapping from error codes returned by regcompO and 
regexec( ) to unspecified printable strings. It generates a string corresponding to the value of the 
encode argument, which the application shall ensure is the last non-zero value returned by I 
regcompO or regexecO with the given value of preg. If encode is not such a value, the content of 
the generated string is unspecified. 

If preg is a null pointer, but encode is a value returned by a previous call to regexec( ) or regcomp (), 
the regerror( ) still generates an error string corresponding to the value of encode, but it might not 
be as detailed under some implementations. 

If the errbitf_size argument is not 0, regerror( ) shall place the generated string into the buffer of 
size errbuf_size bytes pointed to by errbuf. If the string (including the terminating null) cannot fit 
in the buffer, regerror( ) shall truncate the string and null-terminates the result. 

If errbuf_size is 0, regerror( ) shall ignore the errbuf argument, and return the size of the buffer 
needed to hold the generated string. 

If the preg argument to regexecO or regfree () is not a compiled regular expression returned by 
regcomp (), the result is undefined. A preg is no longer treated as a compiled regular expression 
after it is given to regfree( ). 

RETURN VALUE 

Upon successful completion, the regcompO function shall return 0. Otherwise, it shall return an I 
integer value indicating an error as described in <regex.h>, and the content of preg is undefined. I 
If a code is returned, the interpretation shall be as given in <regex.h>. I 

If regcomp () detects an invalid RE, it may return REG_BADPAT, or it may return one of the error I 
codes that more precisely describes the error. I 

Upon successful completion, the regexecO function shall return 0. Otherwise, it shall return I 
REG_NOMATCH to indicate no match, or REG_ENOSYS to indicate that the function is not 
supported. 

Upon successful completion, the regerror( ) function shall return the number of bytes needed to 
hold the entire generated string, including the null termination. If the return value is greater than I 
errbuf_size, the string returned in the buffer pointed to by errbuf has been truncated. Otherwise, it I 
shall return 0 to indicate that the function is not implemented. I 

The regfree( ) function shall return no value. 

ERRORS 

No errors are defined. 

EXAMPLES 

#include <regex.h> 

/* 

* Match string against the extended regular expression in 

* pattern, treating errors as no match. 

•k 

* Return 1 for match, 0 for no match. 

*/ 

int 

match (const char *string, char *pattern) 
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33615 

33616 

33617 

33618 

33619 

33620 

33621 

33622 

33623 

33624 

33625 

33626 

33627 

33628 

33629 

33630 

33631 

33632 

33633 

33634 

33635 

33636 

33637 

33638 

33639 

33640 

33641 

33642 

33643 

33644 

33645 

33646 

33647 

33648 

33649 

33650 

33651 

33652 

33653 

33654 

33655 

33656 

33657 

33658 

33659 

33660 

33661 


{ 

int status; 
regex_t re; 

if (regcomp(&re, pattern, REG_EXTENDED|REG_NOSUB) != 0) { 

return(0); /* Report error. */ 

} 

status = regexec(Sre, string, (size_t) 0, NULL, 0); 
regfree(Sre); 
if (status != 0) { 

return (0); /* Report error. */ 

} 

return(1); 

} 

The following demonstrates how the REG_NOTBOL flag could be used with regexec () to find all 
substrings in a line that match a pattern supplied by a user. (For simplicity of the example, very 
little error checking is done.) 

(void) regcomp (Sre, pattern, 0); 

/* This call to regexec() finds the first match on the line. */ 
error = regexec (Sre, &buffer[0], 1, &pm, 0); 
while (error == 0) { /* While matches found. */ 

/* Substring found between pm.rm_so and pm.rm_eo. */ 

/* This call to regexec() finds the next match. */ 

error = regexec (Sre, buffer + pm.rm_eo, 1, &pm, REG_NOTBOL); 

} 

APPLICATION USAGE 

An application could use: 

regerror(code,preg,(char *)NULL,(size_t)0) 

to find out how big a buffer is needed for the generated string, malloc() a buffer to hold the 
string, and then call regerror () again to get the string. Alternatively, it could allocate a fixed, 
static buffer that is big enough to hold most strings, and then use maUoc() to allocate a larger 
buffer if it finds that this is too small. 

To match a pattern as described in the Commands and Utilities volume of IEEE Std. 1003.1-200x, 
Section 2.13, Pattern Matching Notation, use th efnmatch () function. 

RATIONALE 

The regmatch () function must fill in all nmatch elements of pmatch, where nmatch and pmatch are 
supplied by the application, even if some elements of pmatch do not correspond to 
subexpressions in pattern . The application writer should note that there is probably no reason 
for using a value of nmatch that is larger than preg—>re_nsnb+ 1. 

The REG_NEWLINE flag supports a use of RE matching that is needed in some applications like 
text editors. In such applications, the user supplies an RE asking the application to find a line 
that matches the given expression. An anchor in such an RE anchors at the beginning or end of 
any line. Such an application can pass a sequence of <newline>-separated lines to regexec () as a 
single long string and specify REG_NEWLINE to regcompO to get the desired behavior. The 
application must ensure that there are no explicit <newline>s in pattern if it wants to ensure that 
any match occurs entirely within a single line. 

The REG_NEWLINE flag affects the behavior of regexec (), but it is in the cflags parameter to 
regcompO to allow flexibility of implementation. Some implementations will want to generate 
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the same compiled RE in regcompO regardless of the setting of REG_NEWLINE and have 
regexec( ) handle anchors differently based on the setting of the flag. Other implementations will 
generate different compiled REs based on the REG_NEWLINE. 

The REG_ICASE flag supports the operations taken by the grep -i option and the historical 
implementations of ex and vi. Including this flag will make it easier for application code to be 
written that does the same thing as these utilities. 

The substrings reported in pmatch [ ] are defined using offsets from the start of the string rather 
than pointers. Since this is a new interface, there should be no impact on historical 
implementations or applications, and offsets should be just as easy to use as pointers. The 
change to offsets was made to facilitate future extensions in which the string to be searched is 
presented to regexecO in blocks, allowing a string to be searched that is not all in memory at 
once. 

A new type regoff_t is used for the elements of pmatch [ ] to ensure that the application can 
represent either the largest possible array in memory (important for an application conforming 
to the Commands and Utilities volume of IEEE Std. 1003.1-200x) or the largest possible file 
(important for an application using the extension where a file is searched in chunks). 

The standard developers rejected the inclusion of a regsubO function that would be used to do 
substitutions for a matched RE. While such a routine would be useful to some applications, its 
utility would be much more limited than the matching function described here. Both RE parsing 
and substitution are possible to implement without support other than that required by the 
ISO C standard, but matching is much more complex than substituting. The only difficult part of 
substitution, given the information supplied by regexec( ), is finding the next character in a string 
when there can be multibyte characters. That is a much larger issue, and one that needs a more 
general solution. 

The errno variable has not been used for error returns to avoid filling the errno name space for 
this feature. 

The interface is defined so that the matched substrings rm_sp and rm_ep are in a separate 
regmatch_t structure instead of in regex_t- This allows a single compiled RE to be used 
simultaneously in several contexts; in mainO and a signal handler, perhaps, or in multiple 
threads of lightweight processes. (The preg argument to regexec( ) is declared with type const, so 
the implementation is not permitted to use the structure to store intermediate results.) It also 
allows an application to request an arbitrary number of substrings from an RE. The number of 
subexpressions in the RE is reported in re_nsnb in preg. With this change to regexecO, 
consideration was given to dropping the REG_NOSUB flag since the user can now specify this 
with a zero nmatch argument to regexecO- However, keeping REG_NOSUB allows an 
implementation to use a different (perhaps more efficient) algorithm if it knows in regcompO 
that no subexpressions need be reported. The implementation is only required to fill in pmatch if 
nmatch is not zero and if REG_NOSUB is not specified. Note that the size_t type, as defined in 
the ISO C standard, is unsigned, so the description of regexec( ) does not need to address 
negative values of nmatch. 

REG_NOTBOL was added to allow an application to do repeated searches for the same pattern 
in a line. If the pattern contains a circumflex character that should match the beginning of a line, 
then the pattern should only match when matched against the beginning of the line. Without 
the REG_NOTBOL flag, the application could rewrite the expression for subsequent matches, 
but in the general case this would require parsing the expression. The need for REG_NOTEOL is 
not as clear; it was added for symmetry. 

The addition of the regerrorO function addresses the historical need for portable application 
programs to have access to error information more than "Function failed to compile/match your 
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33710 RE for unknown reasons". 

33711 This interface provides for two different methods of dealing with error conditions. The specific 

33712 error codes (REG_EBRACE, for example), defined in <regex.h>, allow an application to recover 

33713 from an error if it is so able. Many applications, especially those that use patterns supplied by a 

33714 user, will not try to deal with specific error cases, but will just use regerror( ) to obtain a human- 

33715 readable error message to present to the user. 

33716 The regerror( ) function uses a scheme similar to confstr( ) to deal with the problem of allocating 

33717 memory to hold the generated string. The scheme used by strerror( ) in the ISO C standard was 

33718 considered unacceptable since it creates difficulties for multi-threaded applications. 

33719 The preg argument is provided to regerror() to allow an implementation to generate a more 

33720 descriptive message than would be possible with encode alone. An implementation might, for 

33721 example, save the character offset of the offending character of the pattern in a field of preg, and 

33722 then include that in the generated message string. The implementation may also ignore preg. 

33723 A REG_FILENAME flag was considered, but omitted. This flag caused regexec () to match 

33724 patterns as described in the Commands and Utilities volume of IEEE Std. 1003.1-200x, Section 

33725 2.13, Pattern Matching Notation instead of REs. This service is now provided by th e fnmatch() 

33726 function. 

33727 Notice that there is a difference in philosophy between the ISO POSIX-2:1993 standard and 

33728 IEEE Std. 1003.1-200x in how to handle a bad regular expression. The ISO POSIX-2:1993 

33729 standard says that many bad constructs produce undefined results, or that the interpretation is 

33730 undefined. IEEE Std. 1003.1-200x, however, says that the interpretation of such REs is 

33731 unspecified. The term "undefined" means that the action by the application is an error, of 

33732 similar severity to passing a bad pointer to a function. 

33733 The regcompO and regexec () functions are required to accept any null-terminated string as the 

33734 pattern argument. If the meaning of the string is undefined, the behavior of the function is 

33735 unspecified. IEEE Std. 1003.1-200x does not specify how the functions will interpret the pattern; 

33736 they might return error codes, or they might do pattern matching in some completely 

33737 unexpected way, but they should not do something like abort the process. 

33738 FUTURE DIRECTIONS 

33739 None. 

33740 SEE ALSO 

33741 fnmatchO , gtob( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <regex.h>, 

33742 <sys/types.h> 

33743 CHANGE HISTORY 

33744 First released in Issue 4. 

33745 Derived from the ISO POSIX-2 standard. 

33746 Issue 5 

33747 Moved from POSIX2 C-language Binding to BASE. 

33748 Issue 6 

33749 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

33750 The following new requirements on POSIX implementations derive from alignment with the 

33751 Single UNIX Specification: 

33752 • The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 

33753 required for conforming implementations of previous POSIX specifications, it was not 

33754 required for UNIX applications. 
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The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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NAME 

remainder — remainder function 

SYNOPSIS 

xsi tinclude <math.h> 

double remainder(double x, double y); 

DESCRIPTION 

The remainder () function shall return the floating point remainder r-x-ny when y is non-zero. 
The value n is the integral value nearest the exact value x/y. When | n—x/y \ -A, the value n is 
chosen to be even. 

The behavior of remainder () is independent of the rounding mode. 

RETURN VALUE 

The remainder () function shall return the floating point remainder r-x-ny when y is non-zero. 
When y is 0, remainder () shall return NaN (or equivalent if available) and set errno to [EDOM], 

If the value of x is ±Inf, remainder () shall return NaN and set errno to [EDOM], 

If x or y is NaN, then the function shall return NaN and errno may be set to [EDOM]. 

ERRORS 

The remainder () function shall fail if: 

[EDOM] The y argument is 0 or the x argument is positive or negative infinity. 

The remainder () function may fail if: 

[EDOM] The x or y argument is NaN. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

abs (), div (), Idiv (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 
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33791 NAME 

33792 remove — remove a file 

33793 SYNOPSIS 

33794 #include <stdio.h> 

33795 int remove (const char *path) ; 

33796 DESCRIPTION 

33797 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

33798 conflict between the requirements described here and the ISO C standard is unintentional. This I 

33799 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

33800 The remove ( ) function shall cause the file named by the path name pointed to by path to be no 

33801 longer accessible by that name. A subsequent attempt to open that file using that name shall fail, 

33802 unless it is created anew. 

33803 cx If path does not name a directory, remove(path) shall be equivalent to unlinkipath). 

33804 If path names a directory, remove(path) shall be equivalent to rmdir(path). 

33805 RETURN VALUE 

33806 cx Refer to rmdir( ) or unlink( ). 

33807 ERRORS 

33808 cx Refer to rmdir( ) or unlink( ). 

33809 EXAMPLES 

33810 Removing Access to a File 

33811 The following example shows how to remove access to a file named /home/cnd/old_mods. 

33812 #include <stdio.h> 

33813 int status; 

33814 

33815 status = remove (" /home/cnd/old_mods ") ; 

33816 APPLICATION USAGE 

33817 None. 

33818 RATIONALE 

33819 None. 

33820 FUTURE DIRECTIONS 

33821 None. 

33822 SEE ALSO 

33823 rmdir( ), unlink( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdio.h> 

33824 CHANGE HISTORY 

33825 First released in Issue 3. 

33826 Entry included for alignment with the POSIX.1-1988 standard and the ISO C standard. 

33827 Issue 4 

33828 All statements containing references to unlink() and rmdir( ) in the DESCRIPTION, RETURN 

33829 VALUE, and ERRORS sections are marked as extensions. 

33830 The following changes are incorporated for alignment with the ISO C standard: 
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33831 

33832 

33833 

33834 

33835 

33836 

33837 

33838 

33839 


• The type of argument path is changed from char’'' to const char*. 

• The DESCRIPTION is expanded to describe the operation of remove () more completely. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The DESCRIPTION, RETURN VALUE, and ERRORS sections are updated so that if path is 
not a directory, remove () is equivalent to unlink (), and if it is a directory, it is equivalent to 
rnidiri ). 
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33840 NAME 

33841 remque — remove an element from a queue 

33842 SYNOPSIS 

33843 xsi #include <search.h> 

33844 void remque (void * element ); 

33845 

33846 DESCRIPTION 

33847 Refer to insqite (). 
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NAME 

rename — rename a file 

SYNOPSIS 

#include <stdio.h> 

int rename(const char *old, const char * new) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The rename( ) function shall change the name of a file. The old argument points to the path name 
of the file to be renamed. The new argument points to the new path name of the file. 

Notes to Reviewers 

This section with side shading will not appear in the final copy. - Ed. 

Dl, XSH, ERN 287 proposes that "both refer to and both link to" (below) is redundant. POSIX.l 
just has "both refer to", but has no symlinks. Dl, XSH, ERN 286 proposes to replace the 
paragraph with: "If the old argument and the new argumentare path names with the same final 
element, and these path names refer to the same file, and their path prefixes (the predecessors of 
the respective final elements) refer to the same directory, then rename () shall return successfully 
and perform no other action." 

cx If the old argument and the new argument both refer to and both link to the same existing file, 

rename( ) shall return successfully and perform no other action. 

If the old argument points to the path name of a file that is not a directory, the application shall I 
ensure that the new argument does not point to the path name of a directory. If the link named I 
by the new argument exists, it shall be removed and old renamed to new. In this case, a link 
named new shall remain visible to other processes throughout the renaming operation and refer 
either to the file referred to by new or old before the operation began. Write access permission is 
required for both the directory containing old and the directory containing new. 

If the old argument points to the path name of a directory, the application shall ensure that the I 
new argument does not point to the path name of a file that is not a directory. If the directory I 
named by the new argument exists, it shall be removed and old renamed to new. In this case, a 
link named new shall exist throughout the renaming operation and shall refer either to the 
directory referred to by new or old before the operation began. If new names an existing directory, I 
the application shall ensure that it is an empty directory. I 

man If either the old or the new arguments name a symbolic link, rename () shall operate on the I 
symbolic link itself, and shall not resolve the last component of the argument. If old points to a I 
path name that names a symbolic link, the symbolic link shall be renamed. If new points to a 
path name that names a symbolic link, the symbolic link shall be removed. 

cx The application shall ensure that the new path name does not contain a path prefix that names I 

old. Write access permission is required for the directory containing old and the directory 
containing new. If the old argument points to the path name of a directory, write access 
permission may be required for the directory named by old, and, if it exists, the directory named 
by new. 

If the link named by the new argument exists and the file's link count becomes 0 when it is 
removed and no process has the file open, the space occupied by the file shall be freed and the 
file shall no longer be accessible. If one or more processes have the file open when the last link is 
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33893 removed, the link shall be removed before rename( ) returns, but the removal of the file contents 

33894 shall be postponed until all references to the file are closed. 

33895 Upon successful completion, rename( ) shall mark for update the st_ctime and st_mtime fields of 

33896 the parent directory of each file. 

33897 RETURN VALUE 

33898 cx Upon successful completion, rename() shall return 0; otherwise, -1 shall be returned, errno shall 

33899 be set to indicate the error, and neither the file named by old nor the file named by new shall be 

33900 changed or created. 


33901 ERRORS 

33902 The renamei ) function shall fail if: 


33903 CX 

33904 

33905 

33906 


[EACCES] A component of either path prefix denies search permission; or one of the 

directories containing old or new denies write permissions; or, write 
permission is required and is denied for a directory pointed to by the old or 
new arguments. 


33907 cx [EBUSY] The directory named by old or new is currently in use by the system or another 

33908 process, and the implementation considers this an error. 


33909 cx [EEXIST] or [ENOTEMPTY] 

33910 The link named by new is a directory that is not an empty directory. 


33911 cx [EINVAL] The new directory path name contains a path prefix that names the old 

33912 directory. 


33913 CX 

33914 CX 

33915 


[EIO] A physical I/O error has occurred. 

[EISDIR] The new argument points to a directory and the old argument points to a file I 

that is not a directory. 


33916 cx [ELOOP] A loop exists in symbolic links encountered during resolution of the path I 

33917 argument. I 


33918 CX 

33919 

33920 CX 

33921 

33922 

33923 


[EMLINK] The file named by old is a directory, and the link count of the parent directory 

of new would exceed |LINK_MAX}. 

[ENAMETOOLONG] 

The length of the old or new argument exceeds {PATH_MAX} or a path name 
component is longer than {NAME_MAX} while _POSIX_NO_TRUNC is in 
effect. 


33924 cx [ENOENT] The link named by old does not name an existing file, or either old or new 

33925 points to an empty string. 


33926 cx [ENOSPC] The directory that would contain new cannot be extended. 

33927 cx [ENOTDIR] A component of either path prefix is not a directory; or the old argument 

33928 names a directory and new argument names a non-directory file. 


33929 XSI 

33930 

33931 

33932 

33933 

33934 

33935 


[EPERM] or [EACCES] 

The S_ISVTX flag is set on the directory containing the file referred to by old 
and the caller is not the file owner, nor is the caller the directory owner, nor 
does the caller have appropriate privileges; or new refers to an existing file, the 
S_ISVTX flag is set on the directory containing this file, and the caller is not 
the file owner, nor is the caller the directory owner, nor does the caller have 
appropriate privileges. 
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33936 CX 

[EROFS] 

The requested operation requires writing in a directory on a read-only file 

33937 


system. 

33938 CX 

33939 

[EXDEV] 

The links named by new and old are on different file systems and the 
implementation does not support links between file systems. 

33940 

The rename () function may fail if: 

33941 XSI 

[EBUSY] 

The file named by the old or new arguments is a named STREAM. 

33942 

33943 

[ELOOP] 

More than [SYMLOOP_MAX[ symbolic links were encountered during 
resolution of the path argument. 


33944 CX 

33945 

33946 

33947 CX 

33948 

33949 EXAMPLES 

33950 Renaming a File 

33951 The following example shows how to rename a file named /home/cnd/modl to 

33952 /home/cnd/mod2. 

33953 #include <stdio.h> 

33954 int status; 

33955 

33956 status = rename ("/home/cnd/modl", "/home/cnd/mod2" ) ; 

33957 APPLICATION USAGE 

33958 None. 

33959 RATIONALE 

33960 This rename( ) function is equivalent for regular files to that defined by the ISO C standard. Its 

33961 inclusion here expands that definition to include actions on directories and specifies behavior 

33962 when the new parameter names a file that already exists. That specification requires that the 

33963 action of the function be atomic. 

33964 One of the reasons for introducing this function was to have a means of renaming directories 

33965 while permitting implementations to prohibit the use of link() and unlink() with directories, 

33966 thus constraining links to directories to those made by nikdir (). 

33967 The specification that if old and new refer to the same file is intended to guarantee that: 

33968 rename ("x", "x"); 

33969 does not remove the file. 

33970 Renaming dot or dot-dot is prohibited in order to prevent cyclical file system paths. 

33971 See also the descriptions of [ENOTEMPTY] and [ENAMETOOLONG] in rmdir{ ) and [EBUSY] in 

33972 unlink(). For a discussion of [EXDEVJ, see link (). 

33973 FUTURE DIRECTIONS 

33974 None. 


[ENAMETOOLONG] 

As a result of encountering a symbolic link in resolution of the path argument, 
the length of the substituted path name string exceeded {PATH_MAX}. 

[ETXTBSY] The file to be renamed is a pure procedure (shared text) file that is being 

executed. 
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33975 

33976 

33977 

33978 

33979 

33980 

33981 

33982 

33983 

33984 

33985 

33986 

33987 

33988 

33989 

33990 

33991 

33992 

33993 

33994 

33995 

33996 

33997 

33998 

33999 

34000 

34001 

34002 

34003 

34004 

34005 

34006 

34007 

34008 

34009 

34010 

34011 

34012 

34013 

34014 


SEE ALSO 

link (), rmdir(), symlink() r unlink(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <stdio.h> 

CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the POSIX.1-1988 standard. 

Issue 4 

The [EMLINK] error is added to the ERRORS section. 

The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

• The type of arguments old and new are changed from char 51 ' to const char*. 

• The RETURN VALUE section now states that if an error occurs, neither file is changed or 
created. 

The following change is incorporated for alignment with the FIPS requirements: 

• In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 
name component is larger that |NAME_MAX[, is now defined as mandatory and marked as 
an extension. 

Issue 4, Version 2 

The following changes are made for X/OPEN UNIX conformance: 

• The DESCRIPTION is updated to indicate the results of naming a symbolic link in either old 
or new. 

• In the ERRORS section, [EIO] is added to indicate that a physical I/O error has occurred, 
[ELOOP] to indicate that too many symbolic links were encountered during path name 
resolution, and [EPERM] or [EACCES] to indicate a permission check failure when operating 
on directories with S_ISVTX set. 

• In the ERRORS section, a second [ENAMETOOLONG] condition is defined that may report 
excessive length of an intermediate result of path name resolution of a symbolic link. 

Issue 5 

The [EBUSY] error is added to the "may fail" part of the ERRORS section. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 
This is since behavior may vary from one file system to another. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The [EIO] mandatory error condition is added. 

• The [ELOOP] mandatory error condition is added. 

• A second [ENAMETOOLONG] is added as an optional error condition. 

• The [ETXTBSY] optional error condition is added. 

The following changes were made to align with the IEEE P1003.1a draft standard: 
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34015 

34016 

34017 


• Details are added regarding the treatment of symbolic links. 

• The [ELOOP] optional error condition is added. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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34018 

34019 

34020 

34021 

34022 

34023 

34024 

34025 

34026 

34027 

34028 

34029 

34030 

34031 

34032 

34033 

34034 

34035 

34036 

34037 

34038 

34039 

34040 

34041 

34042 

34043 

34044 

34045 

34046 

34047 

34048 

34049 

34050 

34051 

34052 


NAME 

rewind — reset file position indicator in a stream 

SYNOPSIS 

#include <stdio.h> 

void rewind(FILE * stream); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The call: 

rewind(stream) 

shall be equivalent to: 

(void) fseek(stream, 0L, SEEK_SET) 

except that rezvind () also clears the error indicator. 

Because rewind () does not return a value, an application wishing to detect errors should clear 
errno, then call rewind (), and if errno is non-zero, assume an error has occurred. 

RETURN VALUE 

The rewind () function shall return no value. 

ERRORS 

cx Refer to fseek () with the exception of [EINVAL] which does not apply. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

fseek (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdio.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 


1120 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


rewinddir() 


34053 NAME 

34054 rewinddir — reset position of directory stream to the beginning of a directory 

34055 SYNOPSIS 

34056 tinclude <dirent.h> 

34057 void rewinddir (DIR *dirp); 

34058 DESCRIPTION 

34059 The rewinddir () function resets the position of the directory stream to which dirp refers to the 

34060 beginning of the directory. It shall also cause the directory stream to refer to the current state of 

34061 the corresponding directory, as a call to opendir() would have done. If dirp does not refer to a 

34062 directory stream, the effect is undefined. 

34063 After a call to the fork() function, either the parent or child (but not both) may continue I 

34064 xsi processing the directory stream using readdir(), reivinddir(), or seekdir(). If both the parent and 

34065 child processes use these functions, the result is undefined. 

34066 RETURN VALUE 

34067 The rewinddir{ ) function does not return a value. 

34068 ERRORS 

34069 No errors are defined. 

34070 EXAMPLES 

34071 None. 

34072 APPLICATION USAGE 

34073 The rewinddir {) function should be used in conjunction with opendir( ), readdir( ), and closedir( ) to 

34074 examine the contents of the directory. This method is recommended for portability. 

34075 RATIONALE 

34076 None. 

34077 FUTURE DIRECTIONS 

34078 None. 

34079 SEE ALSO 

34080 closedir( ), opendir( ), readdir( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

34081 <dirent.h> <sys/types.h> 

34082 CHANGE HISTORY 

34083 First released in Issue 2. 

34084 Issue 4 

34085 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

34086 XSI-conformant systems. 

34087 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

34088 • The last paragraph of the DESCRIPTION, describing a restriction after a fork() function, is 

34089 added. 

34090 Issue 6 

34091 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

34092 The following new requirements on POSIX implementations derive from alignment with the 

34093 Single UNIX Specification: 

34094 • The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 

34095 required for conforming implementations of previous POSIX specifications, it was not 
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required for UNIX applications. 
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34097 NAME 

34098 rindex — character string operations (LEGACY) 

34099 SYNOPSIS 

34100 xsi #include <strings.h> 

34101 char *rindex(const char *s, int c) ; 

34102 

34103 DESCRIPTION 

34104 The rindex( ) function is identical to strrchr (). 

34105 RETURN VALUE 

34106 Refer to strrchr (). 

34107 ERRORS 

34108 Refer to strrchr (). 

34109 EXAMPLES 

34110 None. 

34111 APPLICATION USAGE 

34112 strrchr( ) is preferred over this function. 

34113 For maximum portability, it is recommended to replace the function call to rindex( ) as follows: 

34114 #define rindex (a, b) strrchr ( (a) , (b) ) 

34115 RATIONALE 

34116 None. 

34117 FUTURE DIRECTIONS 

34118 This function may be withdrawn in a future version. 

34119 SEE ALSO 

34120 strrchr( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <strings.h> 

34121 CHANGE HISTORY 

34122 First released in Issue 4, Version 2. 

34123 Issue 5 

34124 Moved from X/OPEN UNIX extension to BASE. 

34125 Issue 6 

34126 This function is marked LEGACY. 
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34127 

34128 

34129 

34130 

34131 

34132 

34133 

34134 

34135 

34136 

34137 

34138 

34139 

34140 

34141 

34142 

34143 

34144 

34145 

34146 

34147 

34148 

34149 

34150 

34151 

34152 

34153 

34154 

34155 

34156 

34157 

34158 

34159 

34160 


NAME 

rint — round-to-nearest integral value 

SYNOPSIS 

xsi tinclude <math.h> 

double rint(double x); 

DESCRIPTION 

The rint() function shall return the integral value (represented as a double) nearest x in the 
direction of the current rounding mode. The current rounding mode is implementation- 
dependent. 

If the current rounding mode rounds toward negative infinity, then rint() is identical to floor (). 
If the current rounding mode rounds toward positive infinity, then rint () is identical to ceil(). 

RETURN VALUE 

Upon successful completion, the rint () function shall return the integer (represented as a double 
precision number) nearest x in the direction of the current rounding mode. 

When x is ±Inf, rint () shall return x. 

If the value of x is NaN, NaN shall be returned and errno may be set to [EDOM]. 

ERRORS 

The rint () function may fail if: 

[EDOM] The x argument is NaN. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

abs(), isnan (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 
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34161 NAME 

34162 rmdir — remove a directory 

34163 SYNOPSIS 

34164 #include <unistd.h> 


34165 int rmdir (const char *path); 


34166 DESCRIPTION 

34167 The rmdir () function shall remove a directory whose name is given by path . The directory is 

34168 removed only if it is an empty directory. 

34169 If the directory is the root directory or the current working directory of any process, it is 

34170 unspecified whether the function succeeds, or whether it shall fail and set errno to [EBUSY]. 

34171 If path names a symbolic link, then rmdir () shall fail and set errno to [ENOTDIR]. I 

34172 If the path argument refers to a path whose final component is either dot or dot-dot, rmdir () shall I 

34173 fail. I 

34174 If the directory's link count becomes 0 and no process has the directory open, the space occupied I 

34175 by the directory shall be freed and the directory shall no longer be accessible. If one or more 

34176 processes have the directory open when the last link is removed, the dot and dot-dot entries, if 

34177 present, are removed before rmdir( ) returns and no new entries may be created in the directory, 

34178 but the directory is not removed until all references to the directory are closed. 

34179 If the directory is not an empty directory, rmdir ( ) shall fail and set errno to [EEXIST] or I 

34180 [ENOTEMPTY], I 

34181 Upon successful completion, the rmdir( ) function shall mark for update the st_ctime and I 

34182 st_mtime fields of the parent directory. 

34183 RETURN VALUE 

34184 Upon successful completion, the function rmdir( ) shall return 0. Otherwise, -1 shall be returned, 

34185 and errno set to indicate the error. If -1 is returned, the named directory shall not be changed. 


34186 ERRORS 

34187 The rmdir () function shall fail if: 


34188 

34189 


[EACCES] Search permission is denied on a component of the path prefix, or write 

permission is denied on the parent directory of the directory to be removed. 


34190 

34191 


[EBUSY] The directory to be removed is currently in use by the system or some process I 

and the implementation considers this to be an error. I 


34192 

34193 

34194 

34195 

34196 MAN 

34197 MAN 

34198 


[EEXIST] or [ENOTEMPTY] 

The path argument names a directory that is not an empty directory, or there I 
are hard links to the directory other than dot or a single entry in dot-dot. I 

[EINVAL] The path argument contains a last component that is dot. I 

[EIO] A physical 1/O error has occurred. 

[ELOOP] A loop exists in symbolic links encountered during resolution of the path I 

argument. I 


34199 

34200 

34201 


[ENAMETOOLONG] 

The length of the path argument exceeds ]PATH_MAX] or a path name 
component is longer than 


34202 NAME_MAX while _POSIX_NO_TRUNC is in effect. 
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34203 

34204 

34205 

34206 

34207 

34208 

34209 

34210 

34211 

34212 

34213 

34214 

34215 

34216 

34217 

34218 

34219 

34220 

34221 

34222 

34223 

34224 

34225 

34226 

34227 

34228 

34229 

34230 

34231 

34232 

34233 

34234 

34235 

34236 

34237 

34238 

34239 

34240 

34241 

34242 

34243 

34244 

34245 


[ENOENT] A component of path does not name an existing file, or the path argument 

names a nonexistent directory or points to an empty string. 

[ENOTDIR] A component of path is not a directory. 

xsi [EPERM] or [EACCES] 

The S_ISVTX flag is set on the parent directory of the directory to be removed 
and the caller is not the owner of the directory to be removed, nor is the caller 
the owner of the parent directory, nor does the caller have the appropriate 
privileges. 

[EROFS] The directory entry to be removed resides on a read-only file system. 

The rmdir () function may fail if: 

[ELOOP] More than [SYMLOOP_MAX[ symbolic links were encountered during 

resolution of the path argument. 

[ENAMETOOLONG] 

As a result of encountering a symbolic link in resolution of the path argument, 
the length of the substituted path name string exceeded |PATH_MAX}. 

EXAMPLES 

Removing a Directory 

The following example shows how to remove a directory named /home/cnd/modl. 

#include <unistd.h> 
int status; 

status = rmdir("/home/cnd/modl"); 

APPLICATION USAGE 

None. 

RATIONALE 

The rmdir () and rename () functions originated in 4.2 BSD, and they used [ENOTEMPTY] for the 
condition when the directory to be removed does not exist or new already exists. When the 1984 
/usr/group standard was published, it contained [EEXIST] instead. When these functions were 
adopted into System V, the 1984 /usr/group standard was used as a reference. Therefore, several 
existing applications and implementations support/use both forms, and no agreement could be 
reached on either value. All implementations are required to supply both [EEXIST] and 
[ENOTEMPTY] in <errno.h> with distinct values, so that applications can use both values in C- 
language case statements. 

The meaning of deleting pathname/dot is unclear, because the name of the file (directory) in the 
parent directory to be removed is not clear, particularly in the presence of multiple links to a 
directory. 

IEEE Std. 1003.1-200x was silent with regard to the behavior of rmdir () when there are multiple 
hard links to the directory being removed. The requirement to set errno to [EEXIST] or 
[ENOTEMPTY] clarifies the behavior in this case. 

If the processs home directory is being removed, that should be an allowed error. 

Virtually all existing implementations detect [ENOTEMPTY] or the case of dot-dot. The text in 
Section 2.3 on page 35 about returning any one of the possible errors permits that behavior to 
continue. The [ELOOP] error may be returned if more than [SYMLOOP_MAX[ symbolic links 
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34246 

34247 

34248 

34249 

34250 

34251 

34252 

34253 

34254 

34255 

34256 

34257 

34258 

34259 

34260 

34261 

34262 

34263 

34264 

34265 

34266 

34267 

34268 

34269 

34270 

34271 

34272 

34273 

34274 

34275 

34276 

34277 

34278 

34279 

34280 

34281 

34282 

34283 

34284 

34285 

34286 


are encountered during resolution of the path argument. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

mkdir(), remove (), unlink(), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

<unistd.h> 

CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the POSIX.1-1988 standard. 

Issue 4 

The <unistd.h> header is added to the SYNOPSIS section. 

The [ENAMETOOLONG] description is amended. 

The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

• The type of argument path is changed from char* to const char*. 

• The DESCRIPTION is expanded to indicate that, if the directory is a root directory or a 
current working directory, it is unspecified whether the function succeeds, or whether it fails 
and sets errno to [EBUSY]. In Issue 3, the behavior under these circumstances was defined as 
implementation-dependent. 

• The RETURN VALUE section is expanded to direct that if -1 is returned, the directory is not 
changed. 

The following change is incorporated for alignment with the FIPS requirements: 

• In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 
name component is larger that |NAME_MAX] is now defined as mandatory and marked as 
an extension. 

Issue 4, Version 2 

The following changes are made for X/OPEN UNIX conformance: 

• The DESCRIPTION is updated to indicate the results of naming a symbolic link in path. 

• In the ERRORS section, [EIO] is added to indicate that a physical I/O error has occurred, 
[ELOOP] to indicate that too many symbolic links were encountered during path name 
resolution, and [EPERM] or [EACCES] to indicate a permission check failure when operating 
on directories with S_ISVTX set. 

• In the ERRORS section, a second [ENAMETOOLONG] condition is defined that may report 
excessive length of an intermediate result of path name resolution of a symbolic link. 

Issue 6 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 
This is since behavior may vary from one file system to another. 

The following new requirements on POSIX implementations derive from alignment with the 

Single UNIX Specification: 

• The DESCRIPTION is updated to indicate the results of naming a symbolic link in path. 

• The [EIO] mandatory error condition is added. 
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34288 

34289 

34290 


• The [ELOOP] mandatory error condition is added. 

• A second [ENAMETOOLONG] is added as an optional error condition. 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• The [ELOOP] optional error condition is added. 
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34291 

34292 

34293 

34294 

34295 

34296 

34297 

34298 

34299 

34300 

34301 

34302 

34303 

34304 

34305 

34306 

34307 

34308 

34309 

34310 

34311 

34312 

34313 

34314 

34315 

34316 

34317 

34318 

34319 

34320 

34321 

34322 

34323 

34324 

34325 

34326 

34327 

34328 

34329 


NAME 

scalb — load exponent of a radix-independent floating-point number 

SYNOPSIS 

xsi tinclude <math.h> 

double scalb(double x, double n ); 

DESCRIPTION 

The scalb () function shall compute x*r \ where r is the radix of the machine's floating point 
arithmetic. When r is 2, scalb () is equivalent to ldexp(). 

An application wishing to check for error situations should set errno to 0 before calling scalb (). If 
errno is non-zero on return, or the return value is NaN, an error has occurred. 

RETURN VALUE 

Upon successful completion, the scalb () function shall return x*r n . 

If the correct value would overflow, scalb () shall return ±HUGE_VAL (according to the sign of x) 
and set errno to [ERANGE]. 

If the correct value would underflow, scalb () shall return 0 and set errno to [ERANGE]. 

The scalb () function shall return x when x is ±Inf. 

If x or n is NaN, then scalb () shall return NaN and may set errno to [EDOM], 

ERRORS 

The scalb () function shall fail if: 

[ERANGE] The correct value would overflow or underflow. 

The scalb () function may fail if: 

[EDOM] The x or n argument is NaN. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

Idexp (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 

The DESCRIPTION is updated to indicate how an application should check for an error. This 
text was previously published in the APPLICATION USAGE section. 
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34330 NAME 

34331 scanf — convert formatted input 

34332 SYNOPSIS 

34333 #include <stdio.h> 

34334 int scanf (const char * format, ... ) ; 

34335 DESCRIPTION 

34336 Refer to fscanf (). 
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34337 NAME 

34338 sched_get_priority_max, sched_get_priority_min — get priority limits (REALTIME) 

34339 SYNOPSIS 

34340 PS #include <sched.h> 

34341 int sched_get_priority_max (int policy) ; 

34342 int sched_get_priority_min (int policy) ; 

34343 

34344 DESCRIPTION 

34345 The sched_get-priority _max() and sched_get_priority_min () functions return the appropriate 

34346 maximum or minimum, respectively, for the scheduling policy specified by policy. 

34347 The value of policy is one of the scheduling policy values defined in <sched.h>. 

34348 RETURN VALUE 

34349 If successful, the sched_get_priority_max () and sched_get -priority_min () functions shall return the 

34350 appropriate maximum or minimum values, respectively. If unsuccessful, they shall return a 

34351 value of -1 and set errno to indicate the error. 

34352 ERRORS 

34353 The sched_get_priority_max () and sched_get-priority_min () functions shall fail if: 

34354 [EINVAL] The value of the policy parameter does not represent a defined scheduling 

34355 policy. 

34356 EXAMPLES 

34357 None. 

34358 APPLICATION USAGE 

34359 None. 

34360 RATIONALE 

34361 None. 

34362 FUTURE DIRECTIONS 

34363 None. 

34364 SEE ALSO 

34365 sched-getparam (), sched_setparam (), sched_getscheduler (), sched_rr_get-interval (), 

34366 sched_setscheduler (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <sched.h> 

34367 CHANGE HISTORY 

34368 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

34369 Issue 6 

34370 These functions are marked as part of the _POSIX_PRIORITY_SCHEDULING option. 

34371 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

34372 implementation does not support the _POSIX_PRIORITY_SCHEDULING option. 

34373 The [ESRCH] error condition has been removed since these functions do not take a pid 

34374 argument. 
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34375 NAME 

34376 sched_getparam — get scheduling parameters (REALTIME) 

34377 SYNOPSIS 

34378 PS #include <sched.h> 

34379 int sched_getparam (pid_t pid, struct sched_param *param) ; 

34380 

34381 DESCRIPTION 

34382 The sched_getpamm() function shall return the scheduling parameters of a process specified by 

34383 pid in the sched_param structure pointed to by param. 

34384 If a process specified by pid exists, and if the calling process has permission, the scheduling 

34385 parameters for the process whose process ID is equal to pid shall be returned. 

34386 If pid is zero, the scheduling parameters for the calling process shall be returned. The behavior of 

34387 the sched_getparam ( ) function is unspecified if the value of pid is negative. 

34388 RETURN VALUE 

34389 Upon successful completion, the sched_getparam() function shall return zero. If the call to 

34390 sched_getparam () is unsuccessful, the function shall return a value of -1 and set errno to indicate 

34391 the error. 

34392 ERRORS 

34393 The sched_getparam( ) function shall fail if: 

34394 [EPERM] The requesting process does not have permission to obtain the scheduling 

34395 parameters of the specified process. 

34396 [ESRCH] No process can be found corresponding to that specified by pid. 

34397 EXAMPLES 

34398 None. 

34399 APPLICATION USAGE 

34400 None. 

34401 RATIONALE 

34402 None. 

34403 FUTURE DIRECTIONS 

34404 None. 

34405 SEE ALSO 

34406 sched_getschednler(), sched_setparam(), sched_setscheduler( ), the System Interface Definitions 

34407 volume of IEEE Std. 1003.1-200x, <sched.h> 

34408 CHANGE HISTORY 

34409 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

34410 Issue 6 

34411 

34412 

34413 

34414 


The sched_getparam() function is marked as part of the _POSIX_PRIORITY_SCHEDULING 
option. 

The [ENOSYS] error condition has been removed as stubs need not be provided if an 
implementation does not support the _POSIX_PRIORITY_SCHEDULING option. 
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34415 NAME 

34416 sched_getscheduler — get scheduling policy (REALTIME) 

34417 SYNOPSIS 

34418 PS #include <sched.h> 

34419 int sched_getscheduler (pid_t pid) ; 

34420 

34421 DESCRIPTION 

34422 The sched_getschednler( ) function shall return the scheduling policy of the process specified by 

34423 pid. If the value of pid is negative, the behavior of the sched_getschednler() function is 

34424 unspecified. 

34425 The values that can be returned by sched_getschedider( ) are defined in the header file <sched.h>. 

34426 If a process specified by pid exists, and if the calling process has permission, the scheduling 

34427 policy shall be returned for the process whose process ID is equal to pid. 

34428 If pid is zero, the scheduling policy shall be returned for the calling process. 

34429 RETURN VALUE 

34430 Upon successful completion, the sched_getschedider( ) function shall return the scheduling policy 

34431 of the specified process. If unsuccessful, the function shall return -1 and set errno to indicate the 

34432 error. 

34433 ERRORS 

34434 The sched_getsched:der( ) function shall fail if: 

34435 [EPERM] The requesting process does not have permission to determine the scheduling 

34436 policy of the specified process. 

34437 [ESRCH] No process can be found corresponding to that specified by pid. 

34438 EXAMPLES 

34439 None. 

34440 APPLICATION USAGE 

34441 None. 

34442 RATIONALE 

34443 None. 

34444 FUTURE DIRECTIONS 

34445 None. 

34446 SEE ALSO 

34447 sched_getparam (), sched_setparam (), sched_setschedider( ), the System Interface Definitions volume 

34448 of IEEE Std. 1003.1-200x, <sched.h> 

34449 CHANGE HISTORY 

34450 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

34451 Issue 6 

34452 The sched_getscheduler( ) function is marked as part of the _POSIX_PRIORITY_SCHEDULING 

34453 option. 

34454 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

34455 implementation does not support the _POSIX_PRIORITY_SCHEDULING option. 
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34456 NAME 

34457 sched_rr_get_interval — get execution time limits (REALTIME) 

34458 SYNOPSIS 

34459 PS #include <sched.h> 

34460 int sched_rr_get_interval (pid_t pid, struct timespec * interval) ; 

34461 

34462 DESCRIPTION 

34463 The sched_rr_get_interval () function updates the timespec structure referenced by the interval 

34464 argument to contain the current execution time limit (that is, time quantum) for the process 

34465 specified by pid. If pid is zero, the current execution time limit for the calling process shall be 

34466 returned. 

34467 RETURN VALUE 

34468 If successful, the sched_rr_get_interval() function shall return zero. Otherwise, it shall return a 

34469 value of -1 and set errno to indicate the error. 

34470 ERRORS 

34471 The sched 

34472 [ESRCH] 

34473 EXAMPLES 

34474 None. 

34475 APPLICATION USAGE 

34476 None. 

34477 RATIONALE 

34478 None. 

34479 FUTURE DIRECTIONS 

34480 None. 

34481 SEE ALSO 

34482 sched_getparam( ), sched _get_priority_max (), sched_getscheduler (), sched_setparam (), 

34483 sched_setschednler( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <sched.h> 

34484 CHANGE HISTORY 

34485 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

34486 Issue 6 

34487 

34488 

34489 

34490 


The sched_rr_get_interval{) function is marked as part of the _POSIX_PRIORITY_SCHEDULING 
option. 

The [ENOSYS] error condition has been removed as stubs need not be provided if an 
implementation does not support the _POSIX_PRIORITY_SCHEDULING option. 


rr_get_interval () function shall fail if: 

No process can be found corresponding to that specified by pid. 
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34491 NAME 

34492 sched_setparam — set scheduling parameters (REALTIME) 

34493 SYNOPSIS 

34494 PS #include <sched.h> 

34495 int sched_setparam (pid_t pid, const struct sched_param *param) ; 

34496 

34497 DESCRIPTION 

34498 The sched_setpamm() function sets the scheduling parameters of the process specified by pid to 

34499 the values specified by the sched_param structure pointed to by param. The value of the 

34500 sched_priority member in the sched_param structure is any integer within the inclusive priority 

34501 range for the current scheduling policy of the process specified by pid. Higher numerical values 

34502 for the priority represent higher priorities. If the value of pid is negative, the behavior of the 

34503 sched_setparam{ ) function is unspecified. 

34504 If a process specified by pid exists, and if the calling process has permission, the scheduling 

34505 parameters shall be set for the process whose process ID is equal to pid. 

34506 If pid is zero, the scheduling parameters shall be set for the calling process. 

34507 The conditions under which one process has permission to change the scheduling parameters of 

34508 another process are implementation-dependent. 

34509 Implementations may require the requesting process to have the appropriate privilege to set its 

34510 own scheduling parameters or those of another process. 

34511 The target process, whether it is running or not running, resumes execution after all other 

34512 runnable processes of equal or greater priority have been scheduled to run. 

34513 If the priority of the process specified by the pid argument is set higher than that of the lowest 

34514 priority running process and if the specified process is ready to run, the process specified by the 

34515 pid argument preempts a lowest priority running process. Similarly, if the process calling 

34516 sched_setparam() sets its own priority lower than that of one or more other non-empty process 

34517 lists, then the process that is the head of the highest priority list also preempts the calling 

34518 process. Thus, in either case, the originating process might not receive notification of the 

34519 completion of the requested priority change until the higher priority process has executed. 

34520 ss If the scheduling policy of the target process is SCHED_SPORADIC, the value specified by the 

34521 sched_ss_low_priority member of the param argument shall be any integer within the inclusive 

34522 priority range for the sporadic server policy. The sched_ss_repl_period and sched_ss_init_budget 

34523 members of the param argument shall represent the time parameters to be used by the sporadic 

34524 server scheduling policy for the target process. The sched_ss_max_repl member of the param 

34525 argument shall represent the maximum number of replenishments that are allowed to be 

34526 pending simultaneously for the process scheduled under this scheduling policy. 

34527 The specified sched_ss_repl_period must be greater than or equal to the specified 

34528 sched_ss_init_budget for the function to succeed; if it is not, then the function shall fail. 

34529 The value of sched_ss_max_repl shall be within the inclusive range [1,{SS_REPL_MAX}] for the 

34530 function to succeed; if not, the function shall fail. 

34531 If the scheduling policy of the target process is either SCHED_FIFO or SCHED_RR, the 

34532 sched_ss_loiv_priority , sched_ss_repljperiod, and sched_ss_init_budget members of the param 

34533 argument shall have no effect on the scheduling behavior. If the scheduling policy of this process 

34534 is not SCHED_FIFO, SCHED_RR, or SCHED_SPORADIC, including SCHED_OTHER, the 

34535 effects of these members shall be implementation-dependent. 
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34536 If the current scheduling policy for the process specified by pid is not SCHED_FIFO, I 

34537 ss SCHED_RR, or SCHED_SPORADIC , the result is implementation-dependent; this includes the I 

34538 SCHED_OTHER policy. I 

34539 The effect of this function on individual threads is dependent on the scheduling contention 

34540 scope of the threads: 

34541 • For threads with system scheduling contention scope, these functions have no effect on their 

34542 scheduling. 

34543 man • For threads with process scheduling contention scope, the threads' scheduling parameters 

34544 shall not be affected. However, the scheduling of these threads with respect to threads in 

34545 other processes may be dependent on the scheduling parameters of their process, which are 

34546 governed using these functions. 

34547 Notes to Reviewers 

34548 This section with side shading will not appear in the final copy. - Ed. 

34549 Dl, XSH, ERN 299 notes that we need to define "two-level scheduling policy" - volunteers 

34550 needed. 

34551 man If an implementation supports a two-level scheduling model in which library threads are 

34552 multiplexed on top of several kernel scheduled entities, then the underlying kernel scheduled 

34553 entities for the system contention scope threads shall not be affected by these functions. 

34554 The underlying kernel scheduled entities for the process contention scope threads shall have 

34555 their scheduling parameters changed to the value specified in par am. Kernel scheduled entities 

34556 for use by process contention scope threads that are created after this call completes inherit their 

34557 scheduling policy and associated scheduling parameters from the process. 

34558 This function is not atomic with respect to other threads in the process. Threads are allowed to 

34559 continue to execute while this function call is in the process of changing the scheduling policy 

34560 for the underlying kernel scheduled entities used by the process contention scope threads. 

34561 RETURN VALUE 

34562 If successful, the sched_setparam( ) function shall return zero. 

34563 If the call to sched_setparam() is unsuccessful, the priority shall remain unchanged, and the 

34564 function shall return a value of -1 and set errno to indicate the error. 

34565 ERRORS 

34566 The sched_setparam () function shall fail if: 

34567 [EINVAL] One or more of the requested scheduling parameters is outside the range 

34568 defined for the scheduling policy of the specified pid. 

34569 [EPERM] The requesting process does not have permission to set the scheduling 

34570 parameters for the specified process, or does not have the appropriate 

34571 privilege to invoke sched_setparam (). 

34572 [ESRCH] No process can be found corresponding to that specified by pid. 
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34573 EXAMPLES 

34574 None. 

34575 APPLICATION USAGE 

34576 None. 

34577 RATIONALE 

34578 None. 

34579 FUTURE DIRECTIONS 

34580 None. 

34581 SEE ALSO 

34582 sched_getparam(), sched_getschednler(), sched_setscheduler(), the System Interface Definitions 

34583 volume of IEEE Std. 1003.1-200x, <sched.h> 

34584 CHANGE HISTORY 

34585 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 

34586 Issue 6 

34587 The sched_setparam() function is marked as part of the _POSIX_PRIORITY_SCHEDULING 

34588 option. 

34589 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

34590 implementation does not support the _POSIX_PRIORITY_SCHEDULING option. 

34591 The following new requirements on POSIX implementations derive from alignment with the 

34592 Single UNIX Specification: 

34593 • In the DESCRIPTION, the effect of this function on a thread's scheduling parameters is 

34594 added. 

34595 • Sections describing two-level scheduling and atomicity of the function are added. 

34596 The SCHED_SPORADIC scheduling policy is added for alignment with IEEE Std. 1003.1d-1999. I 
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34597 NAME 

34598 sched_setscheduler — set scheduling policy and parameters (REALTIME) 

34599 SYNOPSIS 

34600 PS #include <sched.h> 

34601 int sched_setscheduler (pid_t pid, int policy, 

34602 const struct sched_param *param) ; 

34603 

34604 DESCRIPTION 

34605 The sched_setschednler( ) function sets the scheduling policy and scheduling parameters of the 

34606 process specified by pid to policy and the parameters specified in the sched_param structure 

34607 pointed to by par am, respectively. The value of the schedjpriority member in the sched_param 

34608 structure is any integer within the inclusive priority range for the scheduling policy specified by 

34609 policy. If the value of pid is negative, the behavior of the sched_setschednler() function is 

34610 unspecified. 

34611 The possible values for the policy parameter are defined in the header file <sched.h>. 

34612 If a process specified by pid exists, and if the calling process has permission, the scheduling 

34613 policy and scheduling parameters shall be set for the process whose process ID is equal to pid. 

34614 If pid is zero, the scheduling policy and scheduling parameters shall be set for the calling 

34615 process. 

34616 The conditions under which one process has the appropriate privilege to change the scheduling 

34617 parameters of another process are implementation-dependent. 

34618 Implementations may require that the requesting process have permission to set its own 

34619 scheduling parameters or those of another process. Additionally, implementation-dependent 

34620 restrictions may apply as to the appropriate privileges required to set a process' own scheduling 

34621 policy, or another process' scheduling policy, to a particular value. 

34622 The sched_setschednler( ) function is considered successful if it succeeds in setting the scheduling 

34623 policy and scheduling parameters of the process specified by pid to the values specified by policy 

34624 and the structure pointed to by par am, respectively. 

34625 ss If the scheduling policy specified by policy is SCHED_SPORADIC, the value specified by the I 

34626 sched_ss_low_priority member of the param argument shall be any integer within the inclusive I 

34627 priority range for the sporadic server policy. The sched_ss_repl_period and sched_ss_init_budget I 

34628 members of the param argument shall represent the time parameters used by the sporadic server I 

34629 scheduling policy for the target process. The sched_ss_max_repl member of the param argument I 

34630 shall represent the maximum number of replenishments that are allowed to be pending I 

34631 simultaneously for the process scheduled under this scheduling policy. I 

34632 The specified sched_ss_repl_period must be greater than or equal to the specified I 

34633 sched_ss_init_budget for the function to succeed; if it is not, then the function shall fail. I 

34634 The value of sched_ss_max_repl shall be within the inclusive range [1 ,{SS_REPL_MAX}] for the I 

34635 function to succeed; if not, the function shall fail. I 

34636 If the scheduling policy specified by policy is either SCHED_FIFO or SCHED_RR, the I 

34637 sched_ss_lozv_priority, sched_ss_repl_period, and sched_ss_init_budget members of the param I 

34638 argument shall have no effect on the scheduling behavior. I 

34639 The effect of this function on individual threads is dependent on the scheduling contention I 

34640 scope of the threads: 
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34641 • For threads with system scheduling contention scope, these functions have no effect on their 

34642 scheduling. 

34643 man • For threads with process scheduling contention scope, the threads' scheduling policy and 

34644 associated parameters shall not be affected. However, the scheduling of these threads with 

34645 respect to threads in other processes may be dependent on the scheduling parameters of their 

34646 process, which are governed using these functions. 

34647 man If an implementation supports a two-level scheduling model in which library threads are 

34648 multiplexed on top of several kernel scheduled entities, then the underlying kernel scheduled 

34649 entities for the system contention scope threads shall not be affected by these functions. 

34650 The underlying kernel scheduled entities for the process contention scope threads shall have 

34651 their scheduling policy and associated scheduling parameters changed to the values specified in 

34652 policy and par am, respectively. Kernel scheduled entities for use by process contention scope 

34653 threads that are created after this call completes inherit their scheduling policy and associated 

34654 scheduling parameters from the process. 

34655 This function is not atomic with respect to other threads in the process. Threads are allowed to 

34656 continue to execute while this function call is in the process of changing the scheduling policy 

34657 and associated scheduling parameters for the underlying kernel scheduled entities used by the 

34658 process contention scope threads. 

34659 RETURN VALUE 

34660 Upon successful completion, the function shall return the former scheduling policy of the 

34661 specified process. If the sched_setschednler( ) function fails to complete successfully, the policy 

34662 and scheduling paramenters shall remain unchanged, and the function shall return a value of -1 

34663 and set errno to indicate the error. 

34664 ERRORS 

34665 The sched_setscheduler () function shall fail if: 

34666 [EINVAL] The value of the policy parameter is invalid, or one or more of the parameters 

34667 contained in param is outside the valid range for the specified scheduling 

34668 policy. 

34669 [EPERM] The requesting process does not have permission to set either or both of the 

34670 scheduling parameters or the scheduling policy of the specified process. 

34671 [ESRCH] No process can be found corresponding to that specified by pid. 

34672 EXAMPLES 

34673 None. 

34674 APPLICATION USAGE 

34675 None. 

34676 RATIONALE 

34677 None. 

34678 FUTURE DIRECTIONS 

34679 None. 

34680 SEE ALSO 

34681 sched_getparam( ), sched_getschednler( ), sched_setparam( ), the System Interface Definitions volume 

34682 of IEEE Std. 1003.1-200x, <sched.h> 
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CHANGE HISTORY 

First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 

Issue 6 

The sched_setschedider{) function is marked as part of the _POSIX_PRIORITY_SCHEDULING 
option. 

The [ENOSYS] error condition has been removed as stubs need not be provided if an 
implementation does not support the _POSIX_PRIORITY_SCHEDULING option. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the DESCRIPTION, the effect of this function on a thread's scheduling parameters is 
added. 

• Sections describing two-level scheduling and atomicity of the function are added. 

The SCHED_SPORADIC scheduling policy is added for alignment with IEEE Std. 1003.1d-1999. I 
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34696 NAME 

34697 sched_yield — yield processor 

34698 SYNOPSIS 

34699 psithr #include <sched.h> 

34700 int sched_yield (void) ; 

34701 

34702 DESCRIPTION 

34703 The sched_yield () function forces the running thread to relinquish the processor until it again 

34704 becomes the head of its thread list. It takes no arguments. 

34705 RETURN VALUE 

34706 The sched_yield () function shall return 0 if it completes successfully; otherwise, it shall return a 

34707 value of -1 and set errno to indicate the error. 

34708 ERRORS 

34709 No errors are defined. 

34710 EXAMPLES 

34711 None. 

34712 APPLICATION USAGE 

34713 None. 

34714 RATIONALE 

34715 None. 

34716 FUTURE DIRECTIONS 

34717 None. 

34718 SEE ALSO 

34719 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <sched.h> 

34720 CHANGE HISTORY 

34721 First released in Issue 5. Included for alignment with the POSIX Realtime Extension and the I 

34722 POSIX Threads Extension. I 

34723 Issue 6 

34724 The sched_yield () function is now marked as part of the _POSIX_PRIORITY_SCHEDULING and 

34725 _POSIX_THREADS options. 
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34726 NAME 

34727 seed48 — seed uniformly distributed pseudo-random non-negative long integer generator 

34728 SYNOPSIS 

34729 xsi #include <stdlib.h> 

34730 unsigned short int *seed48(unsigned short int seedl 6v[ 3 ] ) ; 

34731 

34732 DESCRIPTION 

34733 Refer to drand48 (). 


1142 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


seekdirO 


34734 NAME 

34735 seekdir — set position of directory stream 

34736 SYNOPSIS 

34737 xsi #include <dirent.h> 

34738 void seekdir (DIR *dirp, long int loc) ; 

34739 

34740 DESCRIPTION 

34741 The seekdir() function sets the position of the next readdirO operation on the directory stream 

34742 specified by dirp to the position specified by loc. The value of loc should have been returned 

34743 from an earlier call to telldir( ). The new position reverts to the one associated with the directory 

34744 stream when telldir( ) was performed. 

34745 If the value of loc was not obtained from an earlier call to telldirO, or if a call to rewinddirO 

34746 occurred between the call to telldirO and the call to seekdirO , the results of subsequent calls to 

34747 readdir( ) are unspecified. 

34748 RETURN VALUE 

34749 The seekdir( ) function shall return no value. 

34750 ERRORS 

34751 No errors are defined. 

34752 EXAMPLES 

34753 None. 

34754 APPLICATION USAGE 

34755 None. 

34756 RATIONALE 

34757 None. 

34758 FUTURE DIRECTIONS 

34759 None. 

34760 SEE ALSO 

34761 opendir (), readdirO, telldirO , the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

34762 <dirent.h>, <stdio.h>, <sys/types.h> 

34763 CHANGE HISTORY 

34764 First released in Issue 2. 

34765 Issue 4 

34766 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

34767 XSI-conformant systems. 

34768 The type of argument loc is expanded to long int. 

34769 Issue 4, Version 2 

34770 The DESCRIPTION is updated for X/OPEN UNIX conformance to indicate that a call to 

34771 readdirO may produce unspecified results if either loc was not obtained by a previous call to 

34772 telldir( ), or if there is an intervening call to rewinddir( ). 

34773 Issue 6 

34774 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 
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34775 NAME 

34776 select — synchronous I/O multiplexing I 

34777 SYNOPSIS 

34778 tinclude <sys/time.h> | 

34779 int select (int nfds, fd_set * readfds, fd_set * write fds, 

34780 fd_set *errorfds, struct timeval *timeout); 

34781 void FD_CLR(int fd, fd_set *fdset); 

34782 int FD_ISSET (int fd, fd_set *fdset); 

34783 void FD_SET (int fd, fd_set *fdset); 

34784 void FD_ZERO (fd_set *fdset); 

34785 DESCRIPTION | 

34786 The select () function indicates which of the specified file descriptors is ready for reading, ready 

34787 for writing, or has an error condition pending. If the specified condition is false for all of the 

34788 specified file descriptors, select ( ) blocks, up to the specified timeout interval, until the specified 

34789 condition is true for at least one of the specified file descriptors. 

34790 xsr The select () function shall support regular files, terminal and pseudo-terminal devices, I 

34791 STREAMS-based files, FIFOs, pipes, and sockets. The behavior of select () on file descriptors that I 

34792 refer to other types of file is unspecified. 

34793 The nfds argument specifies the range of file descriptors to be tested. The select () function tests 

34794 file descriptors in the range of 0 to nfds- 1. 

34795 If the readfds argument is not a null pointer, it points to an object of type fd_set that on input 

34796 specifies the file descriptors to be checked for being ready to read, and on output indicates 

34797 which file descriptors are ready to read. 

34798 If the ivritefds argument is not a null pointer, it points to an object of type fd_set that on input 

34799 specifies the file descriptors to be checked for being ready to write, and on output indicates 

34800 which file descriptors are ready to write. 

34801 If the errorfds argument is not a null pointer, it points to an object of type fd_set that on input 

34802 specifies the file descriptors to be checked for error conditions pending, and on output indicates 

34803 which file descriptors have error conditions pending. 

34804 Upon successful completion, the objects pointed to by the readfds, ivritefds, and errorfds I 

34805 arguments are modified to indicate which file descriptors are ready for reading, ready for 

34806 writing, or have an error condition pending, respectively. For each file descriptor less than nfds, 

34807 the corresponding bit shall be set on successful completion if it was set on input and the 

34808 associated condition is true for that file descriptor. 

34809 If the timeout argument is not a null pointer, it points to an object of type struct timeval that 

34810 specifies a maximum interval to wait for the selection to complete. If the timeout argument 

34811 points to an object of type struct timeval whose members are 0, select() shall not block. If the I 

34812 timeout argument is a null pointer, select( ) blocks until an event causes one of the masks to be 

34813 returned with a valid (non-zero) value. If the time limit expires before any event occurs that 

34814 would cause one of the masks to be set to a non-zero value, select () shall complete successfully 

34815 and return 0. 

34816 The use of a timeout does not affect any pending timers set up by alarm (), nalarm (), or 

34817 setitimer(). 

34818 Upon successful completion, the object pointed to by the timeout argument may be modified. I 

34819 Implementations may place limitations on the maximum timeout interval supported. All 

34820 implementations shall support a maximum timeout interval of at least 31 days. If the timeout 
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argument specifies a timeout interval greater than the implementation-dependent maximum 
value, the maximum value shall be used as the actual timeout value. Implementations may also 
place limitations on the granularity of timeout intervals. If the requested timeout interval 
requires a finer granularity than the implementation supports, the actual timeout interval shall 
be rounded up to the next supported value. 

If the readfds, writefds, and errorfds arguments are all null pointers and the timeout argument is not 
a null pointer, select () blocks for the time specified, or until interrupted by a signal. If the readfds, 
ivritefds, and errorfds arguments are all null pointers and the timeout argument is a null pointer, 
select () blocks until interrupted by a signal. 

File descriptors associated with regular files shall always select true for ready to read, ready to I 
write, and error conditions. I 

On failure, the objects pointed to by the readfds, ivritefds, and errorfds arguments are not modified. 

If the timeout interval expires without the specified condition being true for any of the specified 
file descriptors, the objects pointed to by the readfds, ivritefds, and errorfds arguments have all bits 
set to 0. 

File descriptor masks of type fd_set can be initialized and tested with FD_CLR(), FD_ISSET(), 
FD_SET(), and FD_ZERO( ). It is unspecified whether each of these is a macro or a function. If a 
macro definition is suppressed in order to access an actual function, or a program defines an 
external identifier with any of these names, the behavior is undefined. 

FD_CLR(fd, Sufdset) Clears the bit for the file descriptor fd in the file descriptor set fdset. 

FD_lSSET(fd, Sufdset) Returns a non-zero value if the bit for the file descriptor fd is set in the file 

descriptor set pointed to by fdset, and 0 otherwise. 

FD_SET(fd, Sufdset) Sets the bit for the file descriptor/d in the file descriptor set fdset. 

FD_ZERO(Snfdset) Initializes the file descriptor set fdset to have zero bits for all file 

descriptors. 

The behavior of these macros is undefined if the fd argument is less than 0 or greater than or I 
equal to FD_SETSIZE, or if fd is not a valid file descriptor, or if any of the arguments are I 
expressions with side effects. I 

A file descriptor for a socket that is listening for connections shall indicate that it is ready for I 
reading, when connections are available. A file descriptor for a socket that is connecting I 
asynchronously shall indicate that it is ready for writing, when a connection has been I 
established. I 

RETURN VALUE 

FD_CLR(), FD_SET( ), and FD_ZERO() return no value. FD_ISSET() a non-zero value if the bit 
for the file descriptor/d is set in the file descriptor set pointed to by fdset, and 0 otherwise. 

Upon successful completion, select() shall return the total number of bits set in the bit masks. I 
Otherwise, -1 shall be returned, and errno shall be set to indicate the error. 

ERRORS 

Under the following conditions, select () shall fail and set errno to: 

[EBADF] One or more of the file descriptor sets specified a file descriptor that is not a 

valid open file descriptor. 

[EINTR] The select () function was interrupted before any of the selected events 

occurred and before the timeout interval expired. 
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34865 

34866 [EINVAL] 

34867 [EINVAL] 

34868 XSR [EINVAL] 

34869 

34870 EXAMPLES 

34871 None. 

34872 APPLICATION USAGE 

34873 None. 

34874 RATIONALE 

34875 None. 

34876 FUTURE DIRECTIONS 

34877 None. 

34878 SEE ALSO 

34879 fcntl(), poll(), read(), write(), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

34880 <sys/time.h> 

34881 CHANGE HISTORY 

34882 First released in Issue 4, Version 2. 

34883 Issue 5 

34884 Moved from X/OPEN UNIX extension to BASE. 

34885 In the ERRORS section, the text has been changed to indicate that [EINVAL] is returned when 

34886 nfds is less than 0 or greater than FD_SETSIZE. It previously stated less than 0, or greater than or 

34887 equal to FD_SETSIZE. 

34888 Text about timeout is moved from the APPLICATION USAGE section to the DESCRIPTION. I 

34889 Issue 6 

34890 The Open Group corrigenda item U026 /6 has been applied, changing the occurrences of readfs 

34891 and writefs in the select () DESCRIPTION to be readfds and writefds . I 

34892 Text referring to sockets is added to the DESCRIPTION. I 

34893 The DESCRIPTION and ERRORS sections are updated so that references to STREAMS are I 

34894 marked as part of the XSI STREAMS Option Group. I 

34895 The following new requirements on POSIX implementations derive from alignment with the I 

34896 Single UNIX Specification: 

34897 • These functions are now mandatory. I 


If SA_RESTART has been set for the interrupting signal, it is implementation- 
dependent whether select () restarts or returns with [EINTR], 

An invalid timeout interval was specified. 

The nfds argument is less than 0 or greater than FD_SETSIZE. I 

One of the specified file descriptors refers to a STREAM or multiplexer that is I 
linked (directly or indirectly) downstream from a multiplexer. I 
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34898 NAME 

34899 sem_close — close a named semaphore (REALTIME) 

34900 SYNOPSIS 

34901 SEM #include <semaphore . h> 

34902 int sem_close (sem_t *sem); 

34903 

34904 DESCRIPTION 

34905 The sem_close( ) function is used to indicate that the calling process is finished using the named 

34906 semaphore indicated by sem. The effects of calling sem_close( ) for an unnamed semaphore (one 

34907 created by sem_init()) are undefined. The sem_close() function deallocates (that is, makes 

34908 available for reuse by a subsequent sem_open () by this process) any system resources allocated 

34909 by the system for use by this process for this semaphore. The effect of subsequent use of the 

34910 semaphore indicated by sem by this process is undefined. If the semaphore has not been 

34911 removed with a successful call to sem_unlink( ), then sem_close( ) has no effect on the state of the 

34912 semaphore. If the sem_unlink{ ) function has been successfully invoked for name after the most 

34913 recent call to semjypen () with 0_CREAT for this semaphore, then when all processes that have 

34914 opened the semaphore close it, the semaphore is no longer accessible. 

34915 RETURN VALUE 

34916 Upon successful completion, a value of zero shall be returned. Otherwise, a value of -1 shall be 

34917 returned and errno set to indicate the error. 

34918 ERRORS 

34919 The sem_close( ) function shall fail if: 

34920 [EINVAL] The sem argument is not a valid semaphore descriptor. 

34921 EXAMPLES 

34922 None. 

34923 APPLICATION USAGE 

34924 The sem_close( ) function is part of the _POSIX_SEMAPHORES option and need not be available 

34925 on all implementations. 

34926 RATIONALE 

34927 None. 

34928 FUTURE DIRECTIONS 

34929 None. 

34930 SEE ALSO 

34931 semctl(), semgeti ), semop(), sem_init( ), sem_open(), sem_unlink{ ), the System Interface Definitions 

34932 volume of IEEE Std. 1003.1-200x, <semaphore.h> 

34933 CHANGE HISTORY 

34934 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

34935 Issue 6 

34936 The sem_close( ) function is marked as part of the _POSIX_SEMAPHORES option. 

34937 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

34938 implementation does not support the _POSIX_SEMAPHORES option. 
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34939 NAME 

34940 sem_destroy — destroy an unnamed semaphore (REALTIME) 

34941 SYNOPSIS 

34942 SEM #include <semaphore . h> 

34943 int sem_destroy (sem_t *sem); 

34944 

34945 DESCRIPTION 

34946 The sem_destroy( ) function is used to destroy the unnamed semaphore indicated by sent. Only a 

34947 semaphore that was created using sem_init( ) may be destroyed using sem_destroy( ); the effect of 

34948 calling sem_destroy( ) with a named semaphore is undefined. The effect of subsequent use of the 

34949 semaphore sem is undefined until sem is re-initialized by another call to sem_init (). 

34950 It is safe to destroy an initialized semaphore upon which no threads are currently blocked. The 

34951 effect of destroying a semaphore upon which other threads are currently blocked is undefined. 

34952 RETURN VALUE 

34953 Upon successful completion, a value of zero shall be returned. Otherwise, a value of -1 shall be 

34954 returned and errno set to indicate the error. 

34955 ERRORS 

34956 The sem_destroy( ) function shall fail if: 

34957 [EINVAL] The sem argument is not a valid semaphore. 

34958 The sem_destroy( ) function may fail if: 

34959 [EBUSY] There are currently processes blocked on the semaphore. 

34960 EXAMPLES 

34961 None. 

34962 APPLICATION USAGE 

34963 The sem_destroy () function is part of the _POSIX_SEMAPHORES option and need not be 

34964 available on all implementations. 

34965 RATIONALE 

34966 None. 

34967 FUTURE DIRECTIONS 

34968 None. 

34969 SEE ALSO 

34970 semctl(), semget(), semop (), sem_init(), sem_open(), the System Interface Definitions volume of 

34971 IEEE Std. 1003.1-200x, <semaphore.h> 

34972 CHANGE HISTORY 

34973 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

34974 Issue 6 

34975 The sem_destroy( ) function is marked as part of the _POSIX_SEMAPHORES option. 

34976 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

34977 implementation does not support the _POSIX_SEMAPHORES option. 
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34978 NAME 

34979 sem_getvalue — get the value of a semaphore (REALTIME) 

34980 SYNOPSIS 

34981 SEM #include <semaphore . h> 

34982 int sem_getvalue (sem_t *sem, int *sval); 

34983 

34984 DESCRIPTION 

34985 The sem_getvalue( ) function updates the location referenced by the sval argument to have the 

34986 value of the semaphore referenced by sem without affecting the state of the semaphore. The 

34987 updated value represents an actual semaphore value that occurred at some unspecified time 

34988 during the call, but it need not be the actual value of the semaphore when it is returned to the 

34989 calling process. 

34990 If sem is locked, then the value returned by sem_getmlue( ) is either zero or a negative number 

34991 whose absolute value represents the number of processes waiting for the semaphore at some 

34992 unspecified time during the call. 

34993 RETURN VALUE 

34994 Upon successful completion, the sem_getmlue( ) function shall return a value of zero. Otherwise, 

34995 it shall return a value of -1 and set errno to indicate the error. 

34996 ERRORS 

34997 The sem_getmlue( ) function shall fail if: 

34998 [EINVAL] The sem argument does not refer to a valid semaphore. 

34999 EXAMPLES 

35000 None. 

35001 APPLICATION USAGE 

35002 The sem_getvalue() function is part of the _POSIX_SEMAPHORES option and need not be 

35003 available on all implementations. 

35004 RATIONALE 

35005 None. 

35006 FUTURE DIRECTIONS 

35007 None. 

35008 SEE ALSO 

35009 semctl(), semget(), semop(), sem_post(), sem_timedivait (), sem_tryivait(), sem_wait(), the System I 

35010 Interface Definitions volume of IEEE Std. 1003.1-200x, <semaphore.h> 

35011 CHANGE HISTORY 

35012 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 

35013 Issue 6 

35014 The sem_getvalue( ) function is marked as part of the _POSIX_SEMAPHORES option. 

35015 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

35016 implementation does not support the _POSIX_SEMAPHORES option. I 

35017 The sem_timedwa.it {) function is added to the SEE ALSO section for alignment with I 

35018 IEEE Std. 1003.1d-1999. I 
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35019 NAME 

35020 sem_init — initialize an unnamed semaphore (REALTIME) 

35021 SYNOPSIS 

35022 SEM #include <semaphore . h> 

35023 int sem_init (sem_t *sem, int pshared, unsigned int value); 

35024 

35025 DESCRIPTION 

35026 The sem_init() function is used to initialize the unnamed semaphore referred to by sem. The 

35027 value of the initialized semaphore is value. Following a successful call to sem_init{), the 

35028 semaphore may be used in subsequent calls to sem_wait(), sem_tryivait(), sem_post(), and 

35029 sem_destroy( ). This semaphore remains usable until the semaphore is destroyed. 

35030 If the pshared argument has a non-zero value, then the semaphore is shared between processes; 

35031 in this case, any process that can access the semaphore sem can use sem for performing 

35032 sem_zvait (), sem_trywait {), sem_post( ), and sem_destroy( ) operations. 

35033 Only sem itself may be used for performing synchronization. The result of referring to copies of 

35034 sem in calls to sem_zvait (), sem _trywait { ), sem_post (), and sem_destroy( ), is undefined. 

35035 If the pshared argument is zero, then the semaphore is shared between threads of the process; any 

35036 thread in this process can use sem for performing sem_wait(), sem_tryzvait(), sem_post(), and 

35037 sem_destroy( ) operations. The use of the semaphore by threads other than those created in the 

35038 same process is undefined. 

35039 Attempting to initialize an already initialized semaphore results in undefined behavior. 

35040 RETURN VALUE 

35041 Upon successful completion, the sem_init() function shall initialize the semaphore in sem. 

35042 Otherwise, it shall return -1 and set errno to indicate the error. 

35043 ERRORS 

35044 The sem_in.it () function shall fail if: 

35045 [EINVAL] The value argument exceeds {SEM_VALUE_MAX}. 

35046 [ENOSPC] A resource required to initialize the semaphore has been exhausted, or the 

35047 limit on semaphores ({SEM_NSEMS_MAX}) has been reached. 

35048 [EPERM] The process lacks the appropriate privileges to initialize the semaphore. 

35049 EXAMPLES 

35050 None. 

35051 APPLICATION USAGE 

35052 The sem_init( ) function is part of the _POSIX_SEMAPHORES option and need not be available 

35053 on all implementations. 

35054 RATIONALE 

35055 Although this volume of IEEE Std. 1003.1-200x fails to specify a successful return value, it is 

35056 likely that a later version may require the implementation to return a value of zero if the call to 

35057 sem_init( ) is successful. 

35058 FUTURE DIRECTIONS 

35059 None. 
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35060 SEE ALSO 

35061 sem_destroy(), sem_post(), sem_timedwait{), sem_trywait{), sem_wait(), the System Interface I 

35062 Definitions volume of IEEE Std. 1003.1-200x, <semaphore.h> 

35063 CHANGE HISTORY 

35064 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 

35065 Issue 6 

35066 The sem_init( ) function is marked as part of the _POSIX_SEMAPHORES option. 

35067 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

35068 implementation does not support the _POSIX_SEMAPHORES option. I 

35069 The sem_timediva.it {) function is added to the SEE ALSO section for alignment with I 

35070 IEEE Std. 1003.1d-1999. I 
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35071 NAME 

35072 sem_open — initialize and open a named semaphore (REALTIME) 

35073 SYNOPSIS 

35074 SEM #include <semaphore . h> 

35075 sem_t *sem_open (const char *name, int of lag, ...); 

35076 


35077 DESCRIPTION 

35078 The semjopen () function establishes a connection between a named semaphore and a process. 

35079 Following a call to sem_open() with semaphore name name, the process may reference the 

35080 semaphore associated with name using the address returned from the call. This semaphore may 

35081 be used in subsequent calls to sem_wait(), sem_trywait(), sem_post(), and sem_close(). The 

35082 semaphore remains usable by this process until the semaphore is closed by a successful call to 

35083 sem_close( ), _exit (), or one of the exec functions. 


35084 The oflag argument controls whether the semaphore is created or merely accessed by the call to 

35085 sem_open(). The following flag bits may be set in oflag : 


35086 

35087 

35088 

35089 

35090 

35091 

35092 


0_CREAT This flag is used to create a semaphore if it does not already exist. If 0_CREAT is 
set and the semaphore already exists, then 0_CREAT has no effect, except as noted 
under 0_EXCL. Otherwise, semjopen () creates a named semaphore. The 0_CREAT 
flag requires a third and a fourth argument: mode, which is of type mode_t, and 
value, which is of type unsigned int. The semaphore is created with an initial 
value of value. Valid initial values for semaphores are less than or equal to 
{SEM_VALUE_M AX}. 


35093 

35094 

35095 

35096 

35097 

35098 


The user ID of the semaphore is set to the effective user ID of the process; the 
group ID of the semaphore is set to a system default group ID or to the effective 
group ID of the process. The permission bits of the semaphore are set to the value 
of the mode argument except those set in the file mode creation mask of the 
process. When bits in mode other than the file permission bits are specified, the 
effect is unspecified. 


35099 

35100 

35101 


After the semaphore named name has been created by sem_open() with the 
CLCREAT flag, other processes can connect to the semaphore by calling 
semjopen () with the same value of name. 


35102 

35103 

35104 

35105 

35106 


0_EXCL If 0_EXCL and CLCREAT are set, sem_open() fails if the semaphore name exists. 

The check for the existence of the semaphore and the creation of the semaphore if 
it does not exist are atomic with respect to other processes executing semjopen () 
with CLEXCL and CLCREAT set. If 0_EXCL is set and CLCREAT is not set, the 
effect is undefined. 


35107 If flags other than CLCREAT and CLEXCL are specified in the oflag parameter, the 

35108 effect is unspecified. 

35109 The name argument points to a string naming a semaphore object. It is unspecified whether the 

35110 name appears in the file system and is visible to functions that take path names as arguments. 

35111 The name argument conforms to the construction rules for a path name. If name begins with the 

35112 slash character, then processes calling sem jopen () with the same value of name shall refer to the 

35113 same semaphore object, as long as that name has not been removed. If name does not begin with 

35114 the slash character, the effect is implementation-dependent. The interpretation of slash 

35115 characters other than the leading slash character in name is implementation-dependent. 

35116 If a process makes multiple successful calls to sem_open() with the same value for name, the 

35117 same semaphore address is returned for each such successful call, provided that there have been 
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35118 no calls to sem_unlink () for this semaphore. 

35119 References to copies of the semaphore produce undefined results. 

35120 RETURN VALUE 

35121 Upon successful completion, the semjopen () function shall return the address of the semaphore. 

35122 Otherwise, it shall return a value of SEM_FAILED and set errno to indicate the error. The symbol 

35123 SEM_FAILED is defined in the header <semaphore.h>. No successful return from semjopen () 

35124 shall return the value SEM_FAILED. 


35125 ERRORS 

35126 If any of the following conditions occur, the semjopen () function shall return SEM_FAILED and 

35127 set errno to the corresponding value: 


35128 

35129 

35130 

[EACCES] 

The named semaphore exists and the permissions specified by oflag are 
denied, or the named semaphore does not exist and permission to create the 
named semaphore is denied. 

35131 

[EEXIST] 

0_CREAT and 0_EXCL are set and the named semaphore already exists. 


35132 

[EINTR] 

The semjopen () operation was interrupted by a signal. 


35133 

35134 

[EINVAL] 

The semjopen () operation is not supported for the given name, or 0_CREAT 
was specified in oflag and value was greater than {SEM_VALUE_MAX}. 

35135 

35136 

[EMFILE] 

Too many semaphore descriptors or file descriptors are currently in use 
this process. 

by 

35137 

35138 

35139 

35140 

[ENAMETOOLONG] 

The length of the name string exceeds {PATH_MAX}, or a path name 
component is longer than |NAME_MAX} while _POSIX_NO_TRUNC is in 
effect. 

35141 

[ENFILE] 

Too many semaphores are currently open in the system. 


35142 

[ENOENT] 

0_CREAT is not set and the named semaphore does not exist. 


35143 

[ENOSPC] 

There is insufficient space for the creation of the new named semaphore. 


35144 EXAMPLES 

35145 None. 




35146 APPLICATION USAGE 

35147 The semjopen () function is part of the _POSIX_SEMAPHORES option and need not be available 

35148 on all implementations. 

35149 RATIONALE 

35150 An earlier version of this volume of IEEE Std. 1003.1-200x required an error return value of -1 

35151 with the type sem_t* for the semjopen () function, which is not guaranteed to be portable across 

35152 implementations. The revised text provides the symbolic error code SEM_FAILED to eliminate 

35153 the type conflict. 

35154 FUTURE DIRECTIONS 

35155 None. 

35156 SEE ALSO 

35157 semctl (), semget (), semop(), sem_close (), sem_post (), sem_timedwait (), sem_trywait (), sem_unlink (), 

35158 sem_iuait( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <semaphore.h> 
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35159 CHANGE HISTORY 

35160 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 

35161 Issue 6 

35162 The sem_open () function is marked as part of the _POSIX_SEMAPHORES option. 

35163 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

35164 implementation does not support the _POSIX_SEMAPHORES option. I 

35165 The sem_timediva.it () function is added to the SEE ALSO section for alignment with I 

35166 IEEE Std. 1003.1d-1999. I 
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35167 NAME 

35168 sem_post — unlock a semaphore (REALTIME) 

35169 SYNOPSIS 

35170 SEM #include <semaphore . h> 

35171 int sem_post (sem_t *sem); 

35172 

35173 DESCRIPTION 

35174 The sem_post() function unlocks the semaphore referenced by sem by performing a semaphore 

35175 unlock operation on that semaphore. 

35176 If the semaphore value resulting from this operation is positive, then no threads were blocked 

35177 waiting for the semaphore to become unlocked; the semaphore value is simply incremented. 

35178 If the value of the semaphore resulting from this operation is zero, then one of the threads 

35179 blocked waiting for the semaphore shall be allowed to return successfully from its call to 

35180 ps sem_wait(). If the Process Scheduling option is supported, the thread to be unblocked shall be I 

35181 chosen in a manner appropriate to the scheduling policies and parameters in effect for the I 

35182 blocked threads. In the case of the schedulers SCHED_FIFO and SCHED_RR, the highest I 

35183 priority waiting thread shall be unblocked, and if there is more than one highest priority thread 

35184 blocked waiting for the semaphore, then the highest priority thread that has been waiting the I 

35185 longest shall be unblocked. If the Process Scheduling option is not defined, the choice of a thread I 

35186 to unblock is unspecified. I 

35187 ss If the Process Sporadic Server option is supported, and the schedule is SCHED_SPORADIC, the I 

35188 semantics are as per SCHED_FIFO above. I 

35189 The sem_post() function shall be reentrant with respect to signals and may be invoked from a I 

35190 signal-catching function. 

35191 RETURN VALUE 

35192 If successful, the sem_post() function shall return zero; otherwise, the function shall return -1 

35193 and set errno to indicate the error. 

35194 ERRORS 

35195 The sem_post( ) function shall fail if: 

35196 [EINVAL] The sem argument does not refer to a valid semaphore. 

35197 EXAMPLES 

35198 None. 

35199 APPLICATION USAGE 

35200 The sem_post( ) function is part of the _POSIX_SEMAPHORES option and need not be available 

35201 on all implementations. 

35202 RATIONALE 

35203 None. 

35204 FUTURE DIRECTIONS 

35205 None. 

35206 SEE ALSO 

35207 semctl(), semget (), semop(), sem_timediva.it {), sem_trywait(), sem_ivait(), the System Interface I 

35208 Definitions volume of IEEE Std. 1003.1-200x, <semaphore.h> 
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35209 CHANGE HISTORY 

35210 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 

35211 Issue 6 

35212 The sem_post () function is marked as part of the _POSIX_SEMAPHORES option. 

35213 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

35214 implementation does not support the _POSIX_SEMAPHORES option. I 

35215 The sem_timedwait() function is added to the SEE ALSO section for alignment with I 

35216 IEEE Std. 1003.1d-1999. I 

35217 SCHED_SPORADIC is added to the list of scheduling policies for which the thread that is to be I 

35218 unblocked is specified for alignment with IEEE Std. 1003.1d-1999. I 
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35219 NAME 

35220 sem_timedwait — lock a semaphore (REALTIME) 

35221 SYNOPSIS 

35222 SEM TMO #include <semaphore . h> 

35223 #include <time.h> 

35224 int sem_timedwait (sem_t *sem, const struct timespec *abs_timeout) ; 

35225 

35226 DESCRIPTION 

35227 The sem_timedwait () function locks the semaphore referenced by sem as in the sem_ivait() 

35228 function. However, if the semaphore cannot be locked without waiting for another process or 

35229 thread to unlock the semaphore by performing a sem_post( ) function, this wait shall be 

35230 terminated when the specified timeout expires. 

35231 The timeout expires when the absolute time specified by abs_timeout passes, as measured by the 

35232 clock on which timeouts are based (that is, when the value of that clock equals or exceeds 

35233 abs_timeout), or if the absolute time specified by abs_timeout has already been passed at the time 

35234 of the call. If the Timers option is supported, the timeout is based on the CLOCK_REALTIME 

35235 clock; if the Timers option is not supported, the timeout is based on the system clock as returned 

35236 by the time( ) function. 

35237 RETURN VALUE 

35238 The sem_timedivait{ ) function shall return zero if the calling process successfully performed the 

35239 semaphore lock operation on the semaphore designated by sem. If the call was unsuccessful, the 

35240 state of the semaphore shall be unchanged, and the function shall return a value of -1 and set 

35241 errno to indicate the error. 

35242 ERRORS 

35243 The sem_timedwait( ) function shall fail if: 

35244 [EINVAL] The sem argument does not refer to a valid semaphore. 

35245 [EINVAL] The thread would have blocked, and the abs_timeont parameter specified a 

35246 nanoseconds field value less than zero or greater than or equal to 1000 

35247 million. 

35248 [ETIMEDOUT] The semaphore could not be locked before the specified timeout expired. 

35249 The sem_timedwait( ) function may fail if: 

35250 [EDEADLK] A deadlock condition was detected. 

35251 [EINTR] A signal interrupted this function. 

35252 EXAMPLES 

35253 None. 

35254 APPLICATION USAGE 

35255 Applications using these functions may be subject to priority inversion, as discussed in the 

35256 System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.290, Priority Inversion. 

35257 The sem_timedwait() function is part of the _POSIX_SEMAPHORES and _POSIX_TIMEOUTS 

35258 options and need not be provided on all implementations. 

35259 RATIONALE 

35260 None. 
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35261 FUTURE DIRECTIONS 

35262 None. 

35263 SEE ALSO 

35264 sem_post(), sem_trywait(), sem_wait(), semctl(), semget(), semop(), time(), the System Interface 

35265 Definitions volume of IEEE Std. 1003.1-200x, <semaphore.h>, <time.h> 

35266 CHANGE HISTORY 

35267 First released in Issue 6. Derived from IEEE Std. 1003.1d-1999. 


1158 


Technical Standard (2000) (Draft February 29, 2000) 




System Interfaces 


sem_trywait() 


35268 NAME 

35269 sem_trywait, sem_wait — lock a semaphore (REALTIME) 

35270 SYNOPSIS 

35271 SEM #include <semaphore . h> 

35272 int sem_trywait (sem_t *sem); 

35273 int sem_wait (sem_t *sem); 

35274 

35275 DESCRIPTION 

35276 The sem_tryzvait() function locks the semaphore referenced by sem only if the semaphore is 

35277 currently not locked; that is, if the semaphore value is currently positive. Otherwise, it does not 

35278 lock the semaphore. 

35279 The sem_zvait( ) function locks the semaphore referenced by sem by performing a semaphore lock 

35280 operation on that semaphore. If the semaphore value is currently zero, then the calling thread 

35281 shall not return from the call to sem_wait() until it either locks the semaphore or the call is 

35282 interrupted by a signal. 

35283 Upon successful return, the state of the semaphore shall be locked and shall remain locked until 

35284 the sem_post( ) function is executed and returns successfully. 

35285 The sem_iuait( ) function is interruptible by the delivery of a signal. 

35286 RETURN VALUE 

35287 The sem_tryzvait() and sem_iuait( ) functions shall return zero if the calling process successfully 

35288 performed the semaphore lock operation on the semaphore designated by sem. If the call was 

35289 unsuccessful, the state of the semaphore shall be unchanged, and the function shall return a 

35290 value of -1 and set errno to indicate the error. 

35291 ERRORS 

35292 The sem_tryzvait( ) and s em_zvait( ) functions shall fail if: 

35293 [EAGAIN] The semaphore was already locked, so it cannot be immediately locked by the 

35294 sem_trywait( ) operation (sem_tryzva.it () only). 

35295 [EINVAL] The sem argument does not refer to a valid semaphore. 

35296 The sem_tryzuait() and sem_zvait( ) functions may fail if: 

35297 [EDEADLK] A deadlock condition was detected. 

35298 [EINTR] A signal interrupted this function. 

35299 EXAMPLES 

35300 None. 

35301 APPLICATION USAGE 

35302 Applications using these functions may be subject to priority inversion, as discussed in the I 

35303 System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.290, Priority Inversion. I 

35304 The sem_tryzvait() and sem_zvait() functions are part of the _POSIX_SEMAPHORES option and 

35305 need not be provided on all implementations. 

35306 RATIONALE 

35307 None. 
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35308 FUTURE DIRECTIONS 

35309 None. 

35310 SEE ALSO 

35311 semctl(), semget( ), semop(), sem_post(), sem_timedwait( ), the System Interface Definitions volume I 

35312 of IEEE Std. 1003.1-200x, <semaphore.h> 

35313 CHANGE HISTORY 

35314 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 

35315 Issue 6 

35316 The sem_tryivait() and sem_wait() functions are marked as part of the _POSIX_SEMAPHORES 

35317 option. 

35318 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

35319 implementation does not support the _POSIX_SEMAPHORES option. I 

35320 The sem_timedwait{ ) function is added to the SEE ALSO section for alignment with I 

35321 IEEE Std. 1003.1d-1999. I 
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35322 NAME 

35323 sem_unlink — remove a named semaphore (REALTIME) 

35324 SYNOPSIS 

35325 SEM #include <semaphore . h> 

35326 int sem_unlink (const char * name) ; 

35327 

35328 DESCRIPTION 

35329 The sem_unlink( ) function removes the semaphore named by the string name. If the semaphore 

35330 named by name is currently referenced by other processes, then sem_unlink( ) has no effect on the 

35331 state of the semaphore. If one or more processes have the semaphore open when sem_unlink( ) is 

35332 called, destruction of the semaphore is postponed until all references to the semaphore have 

35333 been destroyed by calls to sem_close(), _exit(), or exec. Calls to sem_open() to recreate or 

35334 reconnect to the semaphore refer to a new semaphore after sem_unlink( ) is called. The 

35335 sem_unlink( ) call does not block until all references have been destroyed; it shall return 

35336 immediately. 

35337 RETURN VALUE 

35338 Upon successful completion, the sem_unlink{ ) function shall return a value of 0. Otherwise, the 

35339 semaphore shall not be changed and the function shall return a value of -1 and set errno to 

35340 indicate the error. 

35341 ERRORS 

35342 The sem_unlink( ) function shall fail if: 

35343 [EACCES] Permission is denied to unlink the named semaphore. 

35344 [ENAMETOOLONG] 

35345 The length of the name string exceeds |NAME_MAX} while 

35346 POSIX_NO_TRUNC is in effect. 

35347 [ENOENT] The named semaphore does not exist. 

35348 EXAMPLES 

35349 None. 

35350 APPLICATION USAGE 

35351 The sem_unlink( ) function is part of the _POSIX_SEMAPHORES option and need not be 

35352 available on all implementations. 

35353 RATIONALE 

35354 None. 

35355 FUTURE DIRECTIONS 

35356 None. 

35357 SEE ALSO 

35358 semctl(), semget(), semop(), sem_close(), sem_open(), the System Interface Definitions volume of 

35359 IEEE Std. 1003.1-200x, <semaphore.h> 

35360 CHANGE HISTORY 

35361 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

35362 Issue 6 

35363 The sem_unlink( ) function is marked as part of the _POSIX_SEMAPHORES option. 

35364 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

35365 implementation does not support the _POSIX_SEMAPHORES option. 
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35366 NAME 

35367 sem_wait — lock a semaphore (REALTIME) 

35368 SYNOPSIS 

35369 SEM #include <semaphore . h> 

35370 int sem_wait (sem_t *sem); 

35371 

35372 DESCRIPTION 

35373 Refer to sem_trywa.it {). 
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35374 NAME 

35375 semctl — XSI semaphore control operations 

35376 SYNOPSIS 

35377 XSI #include <sys/sem.h> 

35378 int semctl (int semid, int semnum, int cmd, . . . ) ; 

35379 


35380 DESCRIPTION 

35381 The semctl () function operates on XSI semaphores (see the System Interface Definitions volume I 

35382 of IEEE Std. 1003.1-200x, Section 3.439, XSI Semaphore). It is unspecified whether this function I 

35383 interoperates with the realtime interprocess communication facilities defined in Section 2.8 on 

35384 page 59. 

35385 The semctl () function provides a variety of semaphore control operations as specified by cmd. 

35386 The fourth argument is optional and depends upon the operation requested. If required, it is of 

35387 type union semun, which the application shall explicitly declare: I 


35388 union semun { 

35389 int val; 

35390 struct semid_ds *buf; 

35391 unsigned short *array; 

35392 } arg; 


35393 The following semaphore control operations as specified by cmd are executed with respect to the 

35394 semaphore specified by semid and semnum. The level of permission required for each operation 

35395 is shown with each command; see Section 2.7 on page 57. The symbolic names for the values of 

35396 cmd are defined by the <sys/sem.h> header: 


35397 


GETVAL Return the value of semval ; see <sys/sem.h>. Requires read permission. 


35398 

35399 

35400 

35401 


SETVAL Set the value of semval to arg.val, where arg is the value of the fourth argument 

to semctl (). When this command is successfully executed, the semadj value 
corresponding to the specified semaphore in all processes is cleared. Requires 
alter permission; see Section 2.7 on page 57. 


35402 

GETPID 

Return the 

35403 

GETNCNT 

Return the 

35404 

GETZCNT 

Return the 


value of sempid. Requires read permission, 
value of semncnt. Requires read permission, 
value of semzcnt. Requires read permission. 


35405 The following values of cmd operate on each semval in the set of semaphores: 


35406 

35407 

35408 


GETALL Return the value of semval for each semaphore in the semaphore set and place 

into the array pointed to by arg.array , where arg is the fourth argument to 
semctl (). Requires read permission. 


35409 

35410 

35411 

35412 

35413 


SETALL Set the value of semval for each semaphore in the semaphore set according to 

the array pointed to by arg.array, where arg is the fourth argument to semctl (). 
When this command is successfully executed, the semadj values corresponding 
to each specified semaphore in all processes are cleared. Requires alter 
permission. 


35414 The following values of cmd are also available: 


35415 IPC_STAT Place the current value of each member of the semid_ds data structure 

35416 associated with semid into the structure pointed to by arg.buf, where arg is the 

35417 fourth argument to semctl (). The contents of this structure are defined in 
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35418 


<sys/sem.h>. Requires read permission. 

35419 

35420 

35421 

IPC_SET 

Set the value of the following members of the semid_ds data structure 
associated with semid to the corresponding value found in the structure 
pointed to by arg.buf, where arg is the fourth argument to semctl (): 

35422 

35423 

35424 


sem_perm.uid 
sem_perm.gid 
sem_perm.mode 

35425 

35426 

35427 


The mode bits specified in Section 2.7.1 on page 57 are copied into the 
corresponding bits of the semjperm.mode associated with semid. The stored 
values of any other bits are unspecified. 

35428 

35429 

35430 

35431 


This command can only be executed by a process that has an effective user ID 
equal to either that of a process with appropriate privileges or to the value of 
sem_perm.cmd or semjperm.idd in the semid_ds data structure associated with 
semid. 

35432 

35433 

35434 

35435 

35436 

35437 

IPC_RMID 

Remove the semaphore identifier specified by semid from the system and 
destroy the set of semaphores and semid_ds data structure associated with it. 
This command can only be executed by a process that has an effective user ID 
equal to either that of a process with appropriate privileges or to the value of 
sem_perm.cmd or semjperm.uid in the semid_ds data structure associated with 
semid. 

35438 RETURN VALUE 

35439 If successful, the value returned by semctl( ) depends on cmd as follows: 

35440 

GETVAL 

The value of semval. 

35441 

GETPID 

The value of sempid. 

35442 

GETNCNT 

The value of semncnt. 

35443 

GETZCNT 

The value of semzcnt. 

35444 

All others 

0. 


35445 Otherwise, semctl( ) shall return -1 and set errno to indicate the error. 

35446 ERRORS 

35447 The semctl( ) function shall fail if: 


35448 

35449 

[EACCES] 

Operation permission is denied to the calling process; see Section 2.7 on page 
57. 

35450 

35451 

35452 

[EINVAL] 

The value of semid is not a valid semaphore identifier, or the value of semnum 
is less than 0 or greater than or equal to sem_nsems, or the value of cmd is not a 
valid command. 

35453 

35454 

35455 

35456 

[EPERM] 

The argument cmd is equal to IPC_RMID or IPC_SET and the effective user ID 
of the calling process is not equal to that of a process with appropriate 
privileges and it is not equal to the value of semjperm.cuid or semjperm.uid in 
the data structure associated with semid. 

35457 

35458 

[ERANGE] 

The argument cmd is equal to SETVAL or SETALL and the value to which 
semval is to be set is greater than the system-imposed maximum. 
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35459 EXAMPLES 

35460 None. 

35461 APPLICATION USAGE 

35462 The fourth parameter in the SYNOPSIS section is now specified as ". . ." in order to avoid a 

35463 clash with the ISO C standard when referring to the union semun (as defined in Issue 3) and for 

35464 backward compatibility. 

35465 The POSIX Realtime Extension defines alternative interfaces for interprocess communication. 

35466 Application developers who need to use IPC should design their applications so that modules 

35467 using the IPC routines described in Section 2.7 on page 57 can be easily modified to use the 

35468 alternative interfaces. 

35469 RATIONALE 

35470 None. 

35471 FUTURE DIRECTIONS 

35472 None. 

35473 SEE ALSO 

35474 semget( ), semop (), sem_close{ ), sem_destroy( ), sem_getvalue( ), sem_in.it (), sem_open(), sem_post( ), 

35475 sem_unlink (), sem_wa.it (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

35476 <sys/sem.h>. Section 2.7 on page 57 

35477 CHANGE HISTORY 

35478 First released in Issue 2. 

35479 Derived from Issue 2 of the SVID. 

35480 Issue 4 

35481 The function is no longer marked as OPTIONAL FUNCTIONALITY. 

35482 The <sys/types.h> and <sys/ipc.h> headers are removed from the SYNOPSIS section. 

35483 The last argument is now defined by an ellipsis symbol. In previous issues it was defined as a 

35484 union of the various types required by settings of cmd. These are now defined individually in 

35485 each description of permitted cmd settings. The text of the description of SETALL in the 

35486 DESCRIPTION now refers to the fourth argument instead of arg.bnf. 

35487 In the DESCRIPTION the type of the array is specified in the descriptions of GETALL and 

35488 SETALL. 

35489 The [ENOSYS] error is removed from the ERRORS section. 

35490 A FUTURE DIRECTIONS section is added warning application developers about migration to 

35491 IEEE 1003.4 interfaces for interprocess communication. 

35492 Issue 4, Version 2 

35493 The fourth argument to semctl(), formerly specified in the APPLICATION USAGE section, is 

35494 moved to the DESCRIPTION, and references to its elements are made more precise. 

35495 Issue 5 

35496 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 

35497 DIRECTIONS to the APPLICATION USAGE section. 
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35498 

35499 

35500 

35501 

35502 

35503 

35504 

35505 

35506 

35507 

35508 

35509 

35510 

35511 

35512 

35513 

35514 

35515 

35516 

35517 

35518 

35519 

35520 

35521 

35522 

35523 

35524 

35525 

35526 

35527 

35528 

35529 

35530 

35531 

35532 

35533 

35534 

35535 

35536 

35537 

35538 

35539 


NAME 

semget — get set of XSI semaphores 

SYNOPSIS 

xsi tinclude <sys/sem.h> 

int semget(key_t key, int nsems, int semflg) ; 


DESCRIPTION 

The semget () function operates on XSI semaphores (see the System Interface Definitions volume I 
of IEEE Std. 1003.1-200x, Section 3.439, XSI Semaphore). It is unspecified whether this function I 
interoperates with the realtime interprocess communication facilities defined in Section 2.8 on 
page 59. 

The semget () function shall return the semaphore identifier associated with key. 

A semaphore identifier with its associated semid_ds data structure and its associated set of 
nsems semaphores (see <sys/sem.h>) is created for key if one of the following is true: 

• The argument key is equal to IPC_PRIVATE. 

• The argument key does not already have a semaphore identifier associated with it and ( semflg 
&IPC_CREAT) is non-zero. 

Upon creation, the semid_ds data structure associated with the new semaphore identifier is 
initialized as follows: 


• In the operation permissions structure sem_perm.cmd, sem_perm.uid, semjperm.cgid , and 
semjperm.gid are set equal to the effective user ID and effective group ID, respectively, of the 
calling process. 

• The low-order 9 bits of sem_perm.mode are set equal to the low-order 9 bits of semflg. 

• The variable sem_nsems is set equal to the value of nsems. 

• The variable sem_otime is set equal to 0 and sem_ctime is set equal to the current time. 

• The data structure associated with each semaphore in the set is not initialized. The semctl() 
function with the command SETVAL or SETALL can be used to initialize each semaphore. 

RETURN VALUE 

Upon successful completion, semget () shall return a non-negative integer, namely a semaphore 
identifier; otherwise, it shall return -1 and set errno to indicate the error. 


ERRORS 

The semget () function shall fail if: 


[EACCES] 

[EEXIST] 

[EINVAL] 


[ENOENT] 


A semaphore identifier exists for key, but operation permission as specified by 
the low-order 9 bits of semflg would not be granted; see Section 2.7 on page 57. 

A semaphore identifier exists for the argument key but (( semflg &IPC_CREAT) 
&c&c(semflg &IPC_EXCL)) is non-zero. 

The value of nsems is either less than or equal to 0 or greater than the system- 
imposed limit, or a semaphore identifier exists for the argument key, but the 
number of semaphores in the set associated with it is less than nsems and 
nsems is not equal to 0. 

A semaphore identifier does not exist for the argument key and ( semflg 
&IPC_CREAT) is equal to 0. 
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35540 

35541 

35542 

35543 

35544 

35545 

35546 

35547 

35548 

35549 

35550 

35551 

35552 

35553 

35554 

35555 

35556 

35557 

35558 

35559 

35560 

35561 

35562 

35563 

35564 

35565 

35566 

35567 

35568 

35569 

35570 

35571 

35572 

35573 

35574 

35575 

35576 

35577 

35578 

35579 

35580 

35581 

35582 

35583 

35584 

35585 

35586 

35587 


[ENOSPC] A semaphore identifier is to be created but the system-imposed limit on the 

maximum number of allowed semaphores system-wide would be exceeded. 

EXAMPLES 


Creating a Semaphore Identifier 

The following example gets a unique semaphore key using the ftok() function, then gets a 
semaphore ID associated with that key using the semget () function (the first call also tests to 
make sure the semaphore exists). If the semaphore does not exist, the program creates it, as 
shown by the second call to semget (). In creating the semaphore for the queueing process, the 
program attempts to create one semaphore with read/write permission for all. It also uses the 
IPC_EXCL flag, which forces semget () to fail if the semaphore already exists. 

After creating the semaphore, the program uses a call to semop() to initialize it to the values in 
the sbuf array. The number of processes that can execute concurrently without queuing is 
initially set to 2. The final call to semget () creates a semaphore identifier that can be used later in 
the program. 


#include 

#include 

#include 

#include 

#include 

#include 

#include 

#include 

#include 

#include 

#include 


<sys/types.h> 
<stdio.h> 
<sys/ipc.h> 
<sys/sem.h> 
<sys/stat.h> 
<errno.h> 
<unistd.h> 
<stdlib.h> 
<pwd.h> 

<fcntl.h> 
<limits.h> 


key_t semkey; 
int semid, pfd, fv; 
struct sembuf sbuf; 
char *lgn; 

char filename[PATH_MAX+1] ; 
struct stat outstat; 
struct passwd *pw; 


/* Get unique key for semaphore. */ 
if ((semkey = ftok ("/tmp", 'a')) == (key_t) -1) { 

perror ("IPC error: ftok"); exit (1); 

} 

/* Get semaphore ID associated with this key. */ 
if ((semid = semget (semkey, 0, 0)) == -1) { 

/* Semaphore does not exist - Create. */ 

if ((semid = semget (semkey, 1, IPC_CREAT | IPC_EXCL | S_IRUSR | 
S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH)) != -1) 

{ 

/* Initialize the semaphore. */ 
sbuf.sem_num = 0; 

sbuf.sem_op =2; /* This is the number of runs without queuing. 

sbuf.sem_flg = 0; 
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35588 if (semop (semid, &sbuf, 1) == -1) { 

35589 perror ("IPC error: semop"); exit (1); 

35590 } 

35591 } 

35592 else if (errno == EEXIST) { 

35593 if ((semid = semget (semkey, 0, 0)) == -1) { 

35594 perror ("IPC error 1: semget"); exit (1); 

35595 } 

35596 } 

35597 else { 

35598 perror ("IPC error 2: semget"); exit (1); 

35599 } 

35600 } 

35601 

35602 APPLICATION USAGE 

35603 The POSIX Realtime Extension defines alternative interfaces for interprocess communication. 

35604 Application developers who need to use IPC should design their applications so that modules 

35605 using the IPC routines described in Section 2.7 on page 57 can be easily modified to use the 

35606 alternative interfaces. 

35607 RATIONALE 

35608 None. 

35609 FUTURE DIRECTIONS 

35610 None. 

35611 SEE ALSO 

35612 semctl(), semop (), sem_close(), sem_destroy(), sem_getvalue(), sem_init(), sem_open(), sem_post(), 

35613 sem_unlink(), sem_wait(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

35614 <sys/sem.h>. Section 2.7 on page 57. 

35615 CHANGE HISTORY 

35616 First released in Issue 2. 

35617 Derived from Issue 2 of the SVID. 


35618 Issue 4 

35619 The function is no longer marked as OPTIONAL FUNCTIONALITY. 

35620 The <sys/types.h> and <sys/ipc.h> headers are removed from the SYNOPSIS section. 

35621 The [ENOSYS] error is removed from the ERRORS section. 


35622 A FUTURE DIRECTIONS section is added warning application developers about migration to 

35623 IEEE 1003.4 interfaces for interprocess communication. 


35624 Issue 5 

35625 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 

35626 DIRECTIONS to a new APPLICATION USAGE section. 
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35627 NAME 

35628 semop — XSI semaphore operations 

35629 SYNOPSIS 

35630 XSI #include <sys/sem.h> 

35631 int semop (int semid, struct sembuf *sops, size_t nsops) ; 

35632 


35633 DESCRIPTION 

35634 The semop () function operates on XSI semaphores (see the System Interface Definitions volume I 

35635 of IEEE Std. 1003.1-200x, Section 3.439, XSI Semaphore). It is unspecified whether this function I 

35636 interoperates with the realtime interprocess communication facilities defined in Section 2.8 on 

35637 page 59. 

35638 The semop () function is used to perform atomically a user-defined array of semaphore 

35639 operations on the set of semaphores associated with the semaphore identifier specified by the 

35640 argument semid. 

35641 The argument sops is a pointer to a user-defined array of semaphore operation structures. The 

35642 implementation shall not modify elements of this array unless the application uses 

35643 implementation-dependent extensions. 

35644 The argument nsops is the number of such structures in the array. 


35645 

35646 

35647 

35648 

35649 

35650 


Each structure, sembuf, includes the following members: 


Member Type 

Member Name 

Description 

short 

short 

short 

sem_num 

sem_op 

semjlg 

Semaphore number. 
Semaphore operation. 
Operation flags. 


35651 Each semaphore operation specified by sem_op is performed on the corresponding semaphore 

35652 specified by semid and sem_num. 

35653 The variable semjop specifies one of three semaphore operations: 

35654 1. If sem_op is a negative integer and the calling process has alter permission, one of the 

35655 following shall occur: 

35656 • If semval( see <sys/sem.h>) is greater than or equal to the absolute value of semjop, the 

35657 absolute value of semjop is subtracted from semval . Also, if ( sem_flg &SEM_UNDO) is 

35658 non-zero, the absolute value of semjop is added to the calling process' semadj value for 

35659 the specified semaphore. 

35660 • If semval is less than the absolute value of semjop and ( sem_flg &IPC_NOWAIT) is non- 

35661 zero, semop () shall return immediately. 

35662 • If semval is less than the absolute value of semjop and ( sem_flg &IPC_NOWAIT) is 0, 

35663 semop () shall increment the semncnt associated with the specified semaphore and 

35664 suspend execution of the calling thread until one of the following conditions occurs: 

35665 — The value of semval becomes greater than or equal to the absolute value of semjop. 

35666 When this occurs, the value of semncnt associated with the specified semaphore is 

35667 decremented, the absolute value of semjop is subtracted from semval and, if ( sem_flg 

35668 &SEM_UNDO) is non-zero, the absolute value of semjop is added to the calling 

35669 process' semadj value for the specified semaphore. 
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35670 

35671 

35672 

35673 

35674 

35675 

35676 

35677 

35678 

35679 

35680 

35681 

35682 

35683 

35684 

35685 

35686 

35687 

35688 

35689 

35690 

35691 

35692 

35693 

35694 

35695 

35696 

35697 

35698 

35699 

35700 

35701 

35702 

35703 

35704 

35705 

35706 

35707 

35708 

35709 

35710 

35711 

35712 


— The semid for which the calling thread is awaiting action is removed from the 
system. When this occurs, errno shall be set equal to [EIDRM] and -1 shall be 
returned. 

— The calling thread receives a signal that is to be caught. When this occurs, the value 
of semncnt associated with the specified semaphore is decremented, and the calling 
thread resumes execution in the manner prescribed in sigaction (). 

2. If sem_op is a positive integer and the calling process has alter permission, the value of 
semjop is added to semval and, if ( semjtg &SEM_UNDO) is non-zero, the value of sem_op is 
subtracted from the calling process' semadj value for the specified semaphore. 

3. If sem_op is 0 and the calling process has read permission, one of the following shall occur: 

• If semval is 0, semop () shall return immediately. 

• If semval is non-zero and (semjtg &IPC_NOWAIT) is non-zero, semop () shall return 
immediately. 

• If semval is non-zero and (semjtg &IPC_NOWAIT) is 0, semop() will increment the 
semzcnt associated with the specified semaphore and suspends execution of the calling 
thread until one of the following occurs: 

— The value of semval becomes 0, at which time the value of semzcnt associated with 
the specified semaphore is decremented. 

— The semid for which the calling thread is awaiting action is removed from the 
system. When this occurs, errno shall be set equal to [EIDRM] and -1 shall be 
returned. 

— The calling thread receives a signal that is to be caught. When this occurs, the value 
of semzcnt associated with the specified semaphore is decremented, and the calling 
thread resumes execution in the manner prescribed in sigaction (). 

Upon successful completion, the value of sempid for each semaphore specified in the array 
pointed to by sops shall be set equal to the process ID of the calling process. 

RETURN VALUE 

Upon successful completion, semop () shall return 0; otherwise, it shall return -1 and set errno to 
indicate the error. 


ERRORS 


The semop () function shall fail if: 

[E2BIG] The value of nsops is greater than the system-imposed maximum. 

[EACCES] Operation permission is denied to the calling process; see Section 2.7 on page 


57. 


[EAGAIN] 

[EFBIG] 

[EIDRM] 

[EINTR] 

[EINVAL] 


The operation would result in suspension of the calling process but (semjtg 
&IPC_NOWAIT) is non-zero. 

The value of sem_num is less than 0 or greater than or equal to the number of 
semaphores in the set associated with semid. 

The semaphore identifier semid is removed from the system. 

The semop () function was interrupted by a signal. 

The value of semid is not a valid semaphore identifier, or the number of 
individual semaphores for which the calling process requests a SEM_UNDO 
would exceed the system-imposed limit. 
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35713 

35714 

35715 

35716 

35717 

35718 

35719 

35720 

35721 

35722 

35723 

35724 

35725 

35726 

35727 

35728 

35729 

35730 

35731 

35732 

35733 

35734 

35735 

35736 

35737 

35738 

35739 

35740 

35741 

35742 

35743 

35744 

35745 

35746 

35747 

35748 

35749 

35750 

35751 

35752 

35753 

35754 

35755 

35756 

35757 


[ENOSPC] The limit on the number of individual processes requesting a SEM_UNDO 

would be exceeded. 

[ERANGE] An operation would cause a semval to overflow the system-imposed limit, or 

an operation would cause a semadj value to overflow the system-imposed 
limit. 

EXAMPLES 


Setting Values in Semaphores 

The following example sets the values of the two semaphores associated with the semid 
identifier to the values contained in the sb array. 

#include <sys/sem.h> 
int semid; 

struct sembuf sb[2]; 
int nsops = 2; 
int result; 

/* Adjust value of semaphore in the semaphore array semid. */ 
sb[0].sem_num = 0; 
sb[0].sem_op = -1; 

sb[0].sem_flg = SEM_UNDO | IPC_NOWAIT; 
sb[l].sem_num = 1; 
sb[1].sem_op = 1; 

sb[l],sem_flg = 0; 

result = semop (semid, sb, nsops); 


Creating a Semaphore Identifier 

The following example gets a unique semaphore key using the ftok() function, then gets a 
semaphore ID associated with that key using the semget() function (the first call also tests to 
make sure the semaphore exists). If the semaphore does not exist, the program creates it, as 
shown by the second call to semget (). In creating the semaphore for the queueing process, the 
program attempts to create one semaphore with read/write permission for all. It also uses the 
IPC_EXCL flag, which forces semget () to fail if the semaphore already exists. 

After creating the semaphore, the program uses a call to semop () to initialize it to the values in 
the sbuf array. The number of processes that can execute concurrently without queuing is 
initially set to 2. The final call to semget () creates a semaphore identifier that can be used later in 
the program. 

The final call to semop () acquires the semaphore and waits until it is free; the SEM_UNDO 
option releases the semaphore when the process exits, waiting until there are less than two 
processes running concurrently. 


#include 

#include 

#include 

#include 

#include 

#include 

#include 

#include 


<sys/types.h> 
<stdio.h> 
<sys/ipc.h> 
<sys/sem.h> 
<sys/stat.h> 
<errno.h> 
<unistd.h> 
<stdlib.h> 
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35758 

35759 

35760 

35761 

35762 

35763 

35764 

35765 

35766 

35767 

35768 

35769 

35770 

35771 

35772 

35773 

35774 

35775 

35776 

35777 

35778 

35779 

35780 

35781 

35782 

35783 

35784 

35785 

35786 

35787 

35788 

35789 

35790 

35791 

35792 

35793 

35794 

35795 

35796 

35797 

35798 

35799 

35800 

35801 

35802 

35803 


#include <pwd.h> 

#include <fcntl.h> 

#include <limits.h> 

key_t semkey; 
int semid, pfd, fv; 
struct sembuf sbuf; 
char *lgn; 

char filename[PATH_MAX+1] ; 
struct stat outstat; 
struct passwd *pw; 

/* Get unique key for semaphore. */ 
if ((semkey = ftok ("/tmp", 'a')) == (key_t) -1) { 

perror ("IPC error: ftok"); exit (1); 

} 

/* Get semaphore ID associated with this key. */ 
if ((semid = semget (semkey, 0, 0)) == -1) { 

/* Semaphore does not exist - Create. */ 

if ((semid = semget (semkey, 1, IPC_CREAT | IPC_EXCL | S_IRUSR | 

S_IWUSR | S_IRGRP | S_IWGRP | S_IROTH | S_IWOTH)) != -1) 

{ 

/* Initialize the semaphore. */ 
sbuf.sem_num = 0; 

sbuf.sem_op = 2; /* This is the number of runs without queuing. */ 

sbuf.sem_flg = 0; 

if (semop (semid, &sbuf, 1) == -1) { 

perror ("IPC error: semop"); exit (1); 

} 

} 

else if (errno == EEXIST) { 

if ((semid = semget (semkey, 0, 0)) == -1) { 

perror ("IPC error 1: semget"); exit (1); 

} 

} 

else { 

perror ("IPC error 2: semget"); exit (1); 

} 

} 

sbuf.sem_num = 0; 

sbuf.sem_op = -1; 

sbuf.sem_flg = SEM_UNDO; 

if (semop (semid, &sbuf, 1) == -1) { 

perror ("IPC Error: semop"); exit (1); 

} 


35804 APPLICATION USAGE 

35805 The POSIX Realtime Extension defines alternative interfaces for interprocess communication. 

35806 Application developers who need to use IPC should design their applications so that modules 

35807 using the IPC routines described in Section 2.7 on page 57 can be easily modified to use the 

35808 alternative interfaces. 
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35809 RATIONALE 

35810 None. 

35811 FUTURE DIRECTIONS 

35812 None. 

35813 SEE ALSO 

35814 exec, exit(), fork(), semctl(), semget(), sem_close(), sem_destroy(), sem_getvalue(), sem_in.it (), 

35815 sem_open(), sem_post(), sem_unlink( ), sem_wait(), the System Interface Definitions volume of 

35816 IEEE Std. 1003.1-200x, <sys/ipc.h>, <sys/sem.h>, <sys/types.h>. Section 2.7 on page 57 

35817 CHANGE HISTORY 

35818 First released in Issue 2. 

35819 Derived from Issue 2 of the SVID. 

35820 Issue 4 

35821 The function is no longer marked as OPTIONAL FUNCTIONALITY. 

35822 The <sys/types.h> and <sys/ipc.h> headers are removed from the SYNOPSIS section. 

35823 The type of nsops is changed to size_t. 

35824 The DESCRIPTION is updated to indicate that an implementation does not modify the elements 

35825 of sops unless the application uses implementation-dependent extensions. 

35826 The [ENOSYS] error is removed from the ERRORS section. 

35827 A FUTURE DIRECTIONS section is added warning application developers about migration to 

35828 IEEE 1003.4 interfaces for interprocess communication. 

35829 Issue 5 

35830 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE I 

35831 DIRECTIONS to a new APPLICATION USAGE section. 
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35832 NAME 

35833 send — send a message on a socket 

35834 SYNOPSIS 

35835 tinclude <sys/socket. h> 


35836 ssize_t send(int socket, const void * buffer, size_t length, int flags); 

35837 DESCRIPTION 

35838 The send () functions takes the following arguments: 


35839 

socket 

Specifies the socket file descriptor. 

35840 

buffer 

Points to the buffer containing the message to send. 

35841 

length 

Specifies the length of the message in bytes. 

35842 

35843 

flags 

Specifies the type of message transmission. Values of this argument are 
formed by logically OR'ing zero or more of the following flags: 

35844 


MSG_EOR Terminates a record (if supported by the protocol). 

35845 


MSG_OOB Sends out-of-band data on sockets that support out-of-band 


35846 communications. The significance and semantics of out-of- 

35847 band data are protocol-specific. 

35848 The send( ) function initiates transmission of a message from the specified socket to its peer. The 

35849 send( ) function sends a message only when the socket is connected (including when the peer of a 

35850 connectionless socket has been set via connect( )). 

35851 The length of the message to be sent is specified by the length argument. If the message is too 

35852 l° n g to pass through the underlying protocol, send( ) shall fail and no data shall be transmitted. 

35853 Successful completion of a call to send() does not guarantee delivery of the message. A return 

35854 value of -1 indicates only locally-detected errors. 

35855 If space is not available at the sending socket to hold the message to be transmitted, and the 

35856 socket file descriptor does not have 0_N0NBL0CK set, send( ) shall block until space is 

35857 available. If space is not available at the sending socket to hold the message to be transmitted, 

35858 and the socket file descriptor does have 0_N0NBL0CK set, send( ) shall fail. The select() and 

35859 poll () functions can be used to determine when it is possible to send more data. 

35860 The socket in use may require the process to have appropriate privileges to use the send() 

35861 function. 

35862 RETURN VALUE 

35863 Upon successful completion, send( ) shall return the number of bytes sent. Otherwise, -1 shall be 

35864 returned and errno set to indicate the error. 

35865 ERRORS 

35866 The send( ) function shall fail if: 

35867 [EAGAIN] or [EWOULDBLOCK] 

35868 The socket's file descriptor is marked 0_N0NBL0CK and the requested 

35869 operation would block. 

35870 [EBADF] The socket argument is not a valid file descriptor. 

35871 [ECONNRESET] A connection was forcibly closed by a peer. 

35872 [EDESTADDRREQ] 

35873 The socket is not connection-mode and no peer address is set. 
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35874 [EFAULT] The buffer parameter cannot be accessed. 

35875 [EINTR] A signal interrupted send( ) before any data was transmitted. 

35876 [EMSGSIZE] The message is too large be sent all at once, as the socket requires. 

35877 [ENOTCONN] The socket is not connected or otherwise has not had the peer pre-specified. 

35878 [ENOTSOCK] The socket argument does not refer to a socket. 

35879 [EOPNOTSUPP] The socket argument is associated with a socket that does not support one or 

35880 more of the values set in flags. 

35881 [EPIPE] The socket is shut down for writing, or the socket is connection-mode and is 

35882 no longer connected. In the latter case, and if the socket is of type 

35883 SOCK_STREAM, the SIGPIPE signal is generated to the calling process. 

35884 The send( ) function may fail if: 

35885 [EACCES] The calling process does not have the appropriate privileges. 

35886 [EIO] An I/O error occurred while reading from or writing to the file system. 

35887 [ENETDOWN] The local function used to reach the destination is down. 

35888 [ENETUNREACH] 

35889 No route to the network is present. 

35890 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 

35891 xsr [ENOSR] There were insufficient STREAMS resources available for the operation to 

35892 complete. 

35893 EXAMPLES 

35894 None. 

35895 APPLICATION USAGE 

35896 The send( ) function is identical to sendto( ) with a null pointer destjen argument, and to write( ) if 

35897 no flags are used. 

35898 RATIONALE 

35899 None. 

35900 FUTURE DIRECTIONS 

35901 None. 

35902 SEE ALSO 

35903 connect (), getsockopt(), poll{), recv{), recvfrom(), recvmsg(), select (), sendmsg(), sendto (), 

35904 setsockopt(), shutdoiuni), socket (), the System Interface Definitions volume of 

35905 IEEE Std. 1003.1-200x, <sys/socket.h> 

35906 CHANGE HISTORY 

35907 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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35908 NAME 

35909 sendmsg — send a message on a socket using a message structure 

35910 SYNOPSIS 

35911 tinclude <sys/socket. h> 

35912 ssize_t sendmsg (int socket, const struct msghdr *message, int flags); 

35913 DESCRIPTION 

35914 The sendmsgO function sends a message through a connection-mode or connectionless-mode 

35915 socket. If the socket is connectionless-mode, the message shall be sent to the address specified by 

35916 msghdr. If the socket is connection-mode, the destination address in msghdr is ignored. 

35917 The sendmsg () function takes the following arguments: 


35918 

socket 

Specifies the socket file descriptor. 

35919 

35920 

35921 

message 

Points to a msghdr structure, containing both the destination address and the 
buffers for the outgoing message. The length and format of the address 
depend on the address family of the socket. The msg_flags member is ignored. 

35922 

35923 

flags 

Specifies the type of message transmission. The application may specify 0 or 
the following flag: 

35924 


MSG_EOR Terminates a record (if supported by the protocol). 

35925 


MSG_OOB Sends out-of-band data on sockets that support out-of- 


35926 bound data. The significance and semantics of out-of-band 

35927 data are protocol-specific. 

35928 The msg_iov and msg_iovlen fields of message specify zero or more buffers containing the data to 

35929 be sent. msg_iov points to an array of iovec structures; msg_iovlen shall be set to the dimension of 

35930 this array. In each iovec structure, the iov_base field specifies a storage area and the iovjen field 

35931 gives its size in bytes. Some of these sizes can be zero. The data from each storage area indicated 

35932 by msg_iov is sent in turn. 

35933 Successful completion of a call to sendmsgO does not guarantee delivery of the message. A 

35934 return value of -1 indicates only locally-detected errors. 

35935 If space is not available at the sending socket to hold the message to be transmitted and the 

35936 socket file descriptor does not have 0_N0NBL0CK set, sendmsg( ) function blocks until space is 

35937 available. If space is not available at the sending socket to hold the message to be transmitted 

35938 and the socket file descriptor does have 0_N0NBL0CK set, sendmsg () function shall fail. 

35939 If the socket protocol supports broadcast and the specified address is a broadcast address for the 

35940 socket protocol, sendmsg( ) shall fail if the SO_BROADCAST option is not set for the socket. 

35941 The socket in use may require the process to have appropriate privileges to use the sendmsg () 

35942 function. 

35943 RETURN VALUE 

35944 Upon successful completion, sendmsgO shall return the number of bytes sent. Otherwise, -1 

35945 shall be returned and errno set to indicate the error. 

35946 ERRORS 

35947 The sendmsgi ) function shall fail if: 

35948 [EAGAIN] or [EWOULDBLOCK] 

35949 The socket's file descriptor is marked 0_NONBLOCK and the requested 

35950 operation would block. 
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35951 

35952 

35953 

35954 

35955 

35956 

35957 

35958 

35959 

35960 

35961 

35962 

35963 

35964 

35965 

35966 

35967 

35968 

35969 

35970 

35971 

35972 

35973 

35974 

35975 

35976 

35977 

35978 

35979 

35980 

35981 

35982 

35983 

35984 

35985 

35986 

35987 

35988 

35989 

35990 


[EAFNOSUPPORT] 

Addresses in the specified address family cannot be used with this socket. 

The socket argument is not a valid file descriptor. 

A connection was forcibly closed by a peer. 

The message parameter, or storage pointed to by the msg_name, msg_control, or 
msg_iov fields of the message parameter, or storage pointed to by the iovec 
structures pointed to by the msg_iov field cannot be accessed. 

A signal interrupted s endmsg( ) before any data was transmitted. 

The sum of the iovjen values overflows an ssize_t. 

The message is too large to be sent all at once (as the socket requires), or the 
msg_iovlen member of the msghdr structure pointed to by message is less than 
or equal to 0 or is greater than |IOV_MAX}. 

The socket is connection-mode but is not connected. 

The socket argument does not refer a socket. 

The socket argument is associated with a socket that does not support one or 
more of the values set in flags. 

The socket is shut down for writing, or the socket is connection-mode and is 
no longer connected. In the latter case, and if the socket is of type 
SOCK_STREAM, the SIGPIPE signal is generated to the calling process. 

If the address family of the socket is AF_UNIX, then sendmsg( ) shall fail if: 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[ELOOP] Too many symbolic links were encountered in translating the path name in the 

socket address. 

[ENAMETOOLONG] 

A component of a path name exceeded |NAME_MAX} characters, or an entire 
path name exceeded |PATH_MAX} characters. 

[ENOENT] A component of the path name does not name an existing file or the path 

name is an empty string. 

[ENOTDIR] A component of the path prefix of the path name in the socket address is not a 
directory. 

The sendmsg( ) function may fail if: 

[EACCES] Search permission is denied for a component of the path prefix; or write 

access to the named socket is denied. 

[EDESTADDRREQ] 

The socket is not connection-mode and does not have its peer address set, and 
no destination address was specified. 

[EHOSTUNREACH] 

The destination host cannot be reached (probably because the host is down or 
a remote router cannot reach it). 

[EIO] An I/O error occurred while reading from or writing to the file system. 


[EBADF] 

[ECONNRESET] 

[EFAULT] 

[EINTR] 

[EINVAL] 

[EMSGSIZE] 

[ENOTCONN] 

[ENOTSOCK] 

[EOPNOTSUPP] 

[EPIPE] 
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35991 [EISCONN] A destination address was specified and the socket is already connected. 

35992 [ENETDOWN] The local function used to reach the destination is down. 

35993 [ENETUNREACH] 

35994 No route to the network is present. 

35995 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 

35996 [ENOMEM] Insufficient memory was available to fulfill the request. 

35997 xsr [ENOSR] There were insufficient STREAMS resources available for the operation to 

35998 complete. 

35999 If the address family of the socket is AF_UNIX, then sendmsg( ) may fail if: 

36000 [ENAMETOOLONG] 

36001 Path name resolution of a symbolic link produced an intermediate result 

36002 whose length exceeds {PATH_MAX}. 

36003 EXAMPLES 

36004 Done. 

36005 APPLICATION USAGE 

36006 The select () and poll () functions can be used to determine when it is possible to send more data. 

36007 RATIONALE 

36008 None. 

36009 FUTURE DIRECTIONS 

36010 None. 

36011 SEE ALSO 

36012 getsockopt(), poll(), recv{), recvfrom(), recvmsg(), select (), send(), sendto(), setsockopt(), 

36013 shutdown(), socket (), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

36014 <sys/socket.h> 

36015 CHANGE HISTORY 

36016 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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36017 NAME 

36018 sendto — send a message on a socket 

36019 SYNOPSIS 

36020 tinclude <sys/socket. h> 


36021 

36022 

36023 


ssize_t sendto(int socket, const void *message, size_t length, 
int flags, const struct sockaddr * dest_addr, 
socklen_t dest_len); 


36024 DESCRIPTION 

36025 

36026 

36027 


36028 

36029 

36030 

36031 

36032 

36033 

36034 

36035 

36036 

36037 

36038 

36039 

36040 

36041 

36042 

36043 

36044 

36045 

36046 

36047 

36048 

36049 

36050 

36051 

36052 

36053 


The sendto () function sends a message through a connection-mode or connectionless-mode 
socket. If the socket is connectionless-mode, the message shall be sent to the address specified by 
dest_nddr. If the socket is connection-mode, dest_addr is ignored. 

The sendto () function takes the following arguments: 

socket Specifies the socket file descriptor. 

message Points to a buffer containing the message to be sent. 

length Specifies the size of the message in bytes. 

flags Specifies the type of message transmission. Values of this argument are 

formed by logically OR'ing zero or more of the following flags: 

MSG_EOR Terminates a record (if supported by the protocol). 

MSG_OOB Sends out-of-band data on sockets that support out-of-band 

data. The significance and semantics of out-of-band data are 
protocol-specific. 

dest_addr Points to a sockaddr structure containing the destination address. The length 

and format of the address depend on the address family of the socket. 

destjen Specifies the length of the sockaddr structure pointed to by the dest_addr 

argument. 

If the socket protocol supports broadcast and the specified address is a broadcast address for the 
socket protocol, sendto () shall fail if the SO_BROADCAST option is not set for the socket. 

The dest_addr argument specifies the address of the target. The length argument specifies the 
length of the message. 

Successful completion of a call to sendto () does not guarantee delivery of the message. A return 
value of -1 indicates only locally-detected errors. 

If space is not available at the sending socket to hold the message to be transmitted and the 
socket file descriptor does not have 0_NONBLOCK set, sendto () blocks until space is available. 
If space is not available at the sending socket to hold the message to be transmitted and the 
socket file descriptor does have 0_NONBLOCK set, sendto () shall fail. 

The socket in use may require the process to have appropriate privileges to use the sendto () 
function. 


36054 RETURN VALUE 

36055 Upon successful completion, sendto () shall return the number of bytes sent. Otherwise, -1 shall 

36056 be returned and errno set to indicate the error. 
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36057 ERRORS 


36058 

36059 

36060 

36061 

36062 

36063 

36064 

36065 

36066 

36067 

36068 

36069 

36070 

36071 

36072 

36073 

36074 

36075 

36076 

36077 

36078 

36079 

36080 

36081 

36082 

36083 

36084 

36085 

36086 

36087 

36088 

36089 

36090 

36091 

36092 

36093 

36094 

36095 

36096 


The sendto( ) function shall fail if: 

[EAFNOSUPPORT] 

Addresses in the specified address family cannot be used with this socket. 
[EAGAIN] or [EWOULDBLOCK] 

The socket's file descriptor is marked 0_NONBLOCK and the requested 
operation would block. 


[EBADF] 


The socket argument is not a valid file descriptor. 


[ECONNRESET] A connection was forcibly closed by a peer. 


[EFAULT] 

[EINTR] 

[EMSGSIZE] 

[ENOTCONN] 

[ENOTSOCK] 


The message or destaddr parameter cannot be accessed. 

A signal interrupted s endto() before any data was transmitted. 

The message is too large to be sent all at once, as the socket requires. 
The socket is connection-mode but is not connected. 

The socket argument does not refer to a socket. 


[EOPNOTSUPP] The socket argument is associated with a socket that does not support one or 
more of the values set in flags. 


[EPIPE] 


The socket is shut down for writing, or the socket is connection-mode and is 
no longer connected. In the latter case, and if the socket is of type 
SOCK_STREAM, the SIGPIPE signal is generated to the calling process. 

If the address family of the socket is AF_UNIX, then sendto( ) shall fail if: 

[EIO] An I/O error occurred while reading from or writing to the file system. 

[ELOOP] Too many symbolic links were encountered in translating the path name in the 

socket address. 

[ENAMETOOLONG] 

A component of a path name exceeded |NAME_MAX} characters, or an entire 
path name exceeded |PATH_MAX} characters. 

[ENOENT] A component of the path name does not name an existing file or the path 

name is an empty string. 

[ENOTDIR] A component of the path prefix of the path name in the socket address is not a 
directory. 

The sendto( ) function may fail if: 

[EACCES] Search permission is denied for a component of the path prefix; or write 

access to the named socket is denied. 

[EDESTADDRREQ] 

The socket is not connection-mode and does not have its peer address set, and 
no destination address was specified. 

[EHOSTUNREACH] 

The destination host cannot be reached (probably because the host is down or 
a remote router cannot reach it). 

[EINVAL] The destjen argument is not a valid length for the address family. 
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36097 [EIO] An 1/O error occurred while reading from or writing to the file system. 

36098 [EISCONN] A destination address was specified and the socket is already connected. This 

36099 error may or may not be returned for connection mode sockets. 

36100 [ENETDOWN] The local function used to reach the destination is down. 

36101 [ENETUNREACH] 

36102 No route to the network is present. 

36103 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 

36104 [ENOMEM] Insufficient memory was available to fulfill the request. 

36105 xsr [ENOSR] There were insufficient STREAMS resources available for the operation to 

36106 complete. 

36107 If the address family of the socket is AF_UNIX, then sendto( ) may fail if: 

36108 [ENAMETOOLONG] 

36109 Path name resolution of a symbolic link produced an intermediate result 

36110 whose length exceeds |PATH_MAX}. 

36111 EXAMPLES 

36112 None. 

36113 APPLICATION USAGE 

36114 The select () and poll () functions can be used to determine when it is possible to send more data. 

36115 RATIONALE 

36116 None. 

36117 FUTURE DIRECTIONS 

36118 None. 

36119 SEE ALSO 

36120 getsockopt(), poll(), recv(), recvfrom{), recvmsg(), select {), send(), sendmsg(), setsockopt(), 

36121 shutdown (), socket (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

36122 <sys/socket.h> 

36123 CHANGE HISTORY 

36124 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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36125 

36126 

36127 

36128 

36129 

36130 

36131 

36132 

36133 

36134 

36135 

36136 

36137 

36138 

36139 

36140 

36141 

36142 

36143 

36144 

36145 

36146 

36147 

36148 

36149 

36150 

36151 

36152 

36153 

36154 

36155 

36156 

36157 

36158 

36159 

36160 


NAME 

setbuf — assign buffering to a stream 

SYNOPSIS 

#include <stdio.h> 

void setbuf(FILE * stream, char *buf) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

Except that it returns no value, the function call: 

setbuf(stream, buf) 

shall be equivalent to: 

setvbuf(stream, buf, _IOFBF, BUFSIZ) 

if buf is not a null pointer, or to: 

setvbuf(stream, buf, _IONBF, BUFSIZ) 

if buf is a null pointer. 

RETURN VALUE 

The setbuf () function shall return no value. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

A common source of error is allocating buffer space as an "automatic" variable in a code block, 
and then failing to close the stream in the same block. 

With setbuf), allocating a buffer of {BUFSIZ} bytes does not necessarily imply that all of 
{BUFSIZ} bytes are used for the buffer area. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

fopen (), setvbuf ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdio.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 
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36161 NAME 

36162 setcontext — set current user context 

36163 SYNOPSIS 

36164 xsi #include <ucontext.h> 

36165 int setcontext (const ucontext_t *ucp) ; 

36166 

36167 DESCRIPTION 

36168 Refer to getcon text (). 
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36169 NAME 

36170 setegid — set effective group ID 

36171 SYNOPSIS 

36172 #include <unistd.h> 

36173 int setegid (gid_t gid) ; 

36174 DESCRIPTION 

36175 If gid is equal to the real group ID or the saved set-group-ID, or if the process has appropriate 

36176 privileges, setegid () shall set the effective group ID to gid ; the real group ID, saved set-group-ID, 

36177 and any supplementary group IDs shall remain unchanged. 

36178 The setegid() function shall not affect the supplementary group list in any way. 

36179 RETURN VALUE 

36180 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 

36181 indicate the error. 

36182 ERRORS 


36183 

The setegidO function shall fail if: 

36184 

36185 

[EINVAL] 

The value of the gid argument is invalid and is not supported by the 
implementation. 

36186 

36187 

[EPERM] 

The process does not have appropriate privileges and gid does not match the 
real group ID or the saved set-group-ID. 


36188 EXAMPLES 

36189 None. 

36190 APPLICATION USAGE 

36191 None. 

36192 RATIONALE 

36193 Refer to the RATIONALE section in setuidO- 

36194 FUTURE DIRECTIONS 

36195 None. 

36196 SEE ALSO 

36197 exec, getgid (), setgid (), setuid (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

36198 <sys/types.h>, <unistd.h> 

36199 CHANGE HISTORY 

36200 First released in Issue 6. Derived from the IEEE P1003.1a draft standard. 
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36201 NAME 

36202 setenv — add or change environment variable 

36203 SYNOPSIS 

36204 #include <stdlib.h> 

36205 int setenv (const char *envname, const char *envval, int overwrite) ; 

36206 DESCRIPTION 

36207 The setenv( ) function updates or adds a variable in the environment of the calling process. The 

36208 envname argument points to a string containing the name of an environment variable to be 

36209 added or altered. The environment variable shall be set to the value to which envval points. The 

36210 function shall fail if envname points to a string which contains an ' =' character. If the 

36211 environment variable named by envname already exists and the value of overwrite is non-zero, 

36212 the function shall return success and the environment shall be updated. If the environment 

36213 variable named by envname already exists and the value of overwrite is zero, the function shall 

36214 return success and the environment shall remain unchanged. 

36215 If the application modifies environ or the pointers to which it points, the behavior of setenv( ) is 

36216 undefined. The setenv) ) function shall update the list of pointers to which environ points. 

36217 The setenv( ) function need not be reentrant. A function that is not required to be reentrant is not 

36218 required to be thread-safe. 

36219 RETURN VALUE 

36220 Upon successful completion, zero shall be returned. Otherwise, -1 shall be returned, errno set to 

36221 indicate the error, and the environment shall be unchanged. 

36222 ERRORS 

36223 The setenv) ) function shall fail if: 

36224 [EINVAL] The name argument is a null pointer, points to an empty string, or points to a 

36225 string containing an ' =' character. 

36226 [ENOMEM] Insufficient memory was available to add a variable or its value to the 

36227 environment. 

36228 EXAMPLES 

36229 None. 

36230 APPLICATION USAGE 

36231 None. 

36232 RATIONALE 

36233 Unanticipated results may occur if setenv( ) changes the external variable environ . In particular, 

36234 if the optional envp argument to main () is present, it is not changed, and thus may point to an 

36235 obsolete copy of the environment (as may any other copy of environ). However, other than the 

36236 aforementioned restriction, the developers of IEEE Std. 1003.1-200x intended that the traditional 

36237 method of walking through the environment by way of the environ pointer must be supported. 

36238 It was decided that setenv () should be required by this revision because it addresses a piece of 

36239 missing functionality, and does not impose a significant burden on the implementor. 

36240 There was considerable debate as to whether the System V pntenv( ) function or the BSD setenv () 

36241 function should be required as a mandatory function. The setenv () function was chosen because 

36242 it permitted the implementation of nnsetenv)) function to delete environmental variables, 

36243 without specifying an additional interface. The putenv)) function is available as an XSI 

36244 extension. 
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36245 The standard developers considered requiring that setenv () indicate an error when a call to it 

36246 would result in exceeding |ARG_MAX}. The requirement was rejected since the condition might 

36247 be temporary, with the application eventually reducing the environment size. The ultimate 

36248 success or failure depends on the size at the time of a call to exec, which returns an indication of 

36249 this error condition. 

36250 FUTURE DIRECTIONS 

36251 None. 

36252 SEE ALSO 

36253 getenv (), unsetenv(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

36254 <stdlib.h>, <sys/types.h>, <unistd.h> 

36255 CHANGE HISTORY 

36256 First released in Issue 6. Derived from the IEEE P1003.1a draft standard. 
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36257 NAME 

36258 seteuid — set effective user ID 

36259 SYNOPSIS 

36260 tinclude <unistd.h> 

36261 int seteuid (uid_t uid) ; 

36262 DESCRIPTION 

36263 If uid is equal to the real user ID or the saved set-user-ID, or if the process has appropriate 

36264 privileges, seteuid() shall set the effective user ID to uid ; the real user ID and saved set-user-ID 

36265 shall remain unchanged. 

36266 The seteuid () function shall not affect the supplementary group list in any way. 

36267 RETURN VALUE 

36268 Upon successful completion, 0 shall be returned; otherwise, -1 shall be returned and errno set to 

36269 indicate the error. 

36270 ERRORS 

36271 The seteuid () function shall fail if: 

36272 [EINVAL] The value of the idd argument is invalid and is not supported by the 

36273 implementation. 

36274 [EPERM] The process does not have appropriate privileges and uid does not match the 

36275 real group ID or the saved set-group-ID. 

36276 EXAMPLES 

36277 None. 

36278 APPLICATION USAGE 

36279 None. 

36280 RATIONALE 

36281 Refer to the RATIONALE section in setuid{). 

36282 FUTURE DIRECTIONS 

36283 None. 

36284 SEE ALSO 

36285 exec, geteuid(), getuid(), setuid(), the System Interface Definitions volume of 

36286 IEEE Std. 1003.1-200x, <sys/types.h>, <unistd.h> 

36287 CHANGE HISTORY 

36288 First released in Issue 6. Derived from the IEEE P1003.1a draft standard. 
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36289 NAME 

36290 setgid — set-group-ID 

36291 SYNOPSIS 

36292 #include <unistd.h> 

36293 int setgid (gid_t gid) ; 

36294 DESCRIPTION 

36295 If the process has appropriate privileges, setgid () shall set the real group ID, effective group ID, 

36296 and the saved set-group-ID to gid. 

36297 If the process does not have appropriate privileges, but gid is equal to the real group ID or the 

36298 saved set-group-ID, setgid () shall set the effective group ID to gid ; the real group ID and saved 

36299 set-group-ID shall remain unchanged. 

36300 The setgid () function shall not affect the supplementary group list in any way. 

36301 Any supplementary group IDs of the calling process shall remain unchanged. 

36302 RETURN VALUE 

36303 Upon successful completion, 0 is returned. Otherwise, -1 shall be returned and errno set to 

36304 indicate the error. 

36305 ERRORS 


36306 

The setgid () function shall fail if: 

36307 

36308 

[EINVAL] 

The value of the gid argument is invalid and is not supported by the 
implementation. 

36309 

36310 

[EPERM] 

The process does not have appropriate privileges and gid does not match the 
real group ID or the saved set-group-ID. 


36311 EXAMPLES 

36312 None. 

36313 APPLICATION USAGE 

36314 None. 

36315 RATIONALE 

36316 Refer to the RATIONALE section in setuid{). 

36317 FUTURE DIRECTIONS 

36318 None. 

36319 SEE ALSO 

36320 exec, getgid(), setuid( ), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

36321 <sys/types.h>, <unistd.h> 

36322 CHANGE HISTORY 

36323 First released in Issue 1. 

36324 Derived from Issue 1 of the SVID. 

36325 Issue 4 

36326 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

36327 XSI-conformant systems. 

36328 The following change is incorporated for alignment with the FIPS requirements: 

36329 • All references to the saved set-user-ID are marked as extensions. This is because Issue 4 

36330 defines this mechanism as mandatory, whereas the ISO POSIX-1 standard defines that it is 
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36331 

36332 

36333 

36334 

36335 

36336 

36337 

36338 

36339 

36340 

36341 

36342 

36343 


only supported if _POSIX_SAVED_IDS is set. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 

Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• Functionality associated with _POSIX_SAVED_IDS is now mandated. This is a FIPS 
requirement. 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• The effects of setgid () in processes without appropriate privileges are changed 

• A requirement that the supplementary group list is not affected is added. 
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36344 NAME 

36345 setgrent — reset group database to first entry 

36346 SYNOPSIS 

36347 xsi #include <grp.h> 

36348 void setgrent (void) ; 

36349 

36350 DESCRIPTION 

36351 Refer to endgrent(). 
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36352 NAME 

36353 sethostent — network host database functions 

36354 SYNOPSIS 

36355 #include <netdb.h> 

36356 void sethostent (int stayopen) ; 

36357 DESCRIPTION 

36358 Refer to endhostent (). 
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36359 NAME 

36360 setitimer — set value of interval timer 

36361 SYNOPSIS 

36362 xsi #include <sys/time.h> 

36363 int setitimer (int which, const struct itimerval *value, 

36364 struct itimerval *ovalue) ; 

36365 

36366 DESCRIPTION 

36367 Refer to getitimer () . 
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36368 NAME 

36369 setjmp — set jump point for a non-local goto 

36370 SYNOPSIS 

36371 #include <setjmp.h> 

36372 int set jmp ( jmp_buf env) ; 

36373 DESCRIPTION 

36374 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

36375 conflict between the requirements described here and the ISO C standard is unintentional. This I 

36376 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

36377 A call to setjmpO, shall save the calling environment in its env argument for later use by 

36378 longjmp 0- 

36379 It is unspecified whether setjmp () is a macro or a function. If a macro definition is suppressed in 

36380 order to access an actual function, or a program defines an external identifier with the name 

36381 setjmp, the behavior is undefined. 

36382 All accessible objects have values as of the time longjmp () was called, except that the values of 

36383 objects of automatic storage duration which are local to the function containing the invocation of 

36384 the corresponding setjmp () which do not have volatile-qualified type and which are changed 

36385 between the setjmp () invocation and longjmp () call are indeterminate. 

36386 An application shall ensure that an invocation of setjmpO appears in one of the following I 

36387 contexts only: I 

36388 • The entire controlling expression of a selection or iteration statement 

36389 • One operand of a relational or equality operator with the other operand an integral constant 

36390 expression, with the resulting expression being the entire controlling expression of a 

36391 selection or iteration statement 

36392 • The operand of a unary ' !' operator with the resulting expression being the entire 

36393 controlling expression of a selection or iteration 

36394 • The entire expression of an expression statement (possibly cast to void) 

36395 RETURN VALUE 

36396 If the return is from a direct invocation, setjmpO shall return 0. If the return is from a call to 

36397 longjmp (), setjmp () shall return a non-zero value. 

36398 ERRORS 

36399 No errors are defined. 

36400 EXAMPLES 

36401 None. 

36402 APPLICATION USAGE 

36403 In general, s igsetjmp( ) is more useful in dealing with errors and interrupts encountered in a low- 

36404 level subroutine of a program. 

36405 RATIONALE 

36406 None. 

36407 FUTURE DIRECTIONS 

36408 None. 
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36409 

36410 

36411 

36412 

36413 

36414 

36415 

36416 

36417 

36418 

36419 

36420 

36421 

36422 

36423 

36424 


SEE ALSO 

longjmp (), sigsetjmp (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

<setjmp.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

This issue states that setjmpO is a macro or a function; previous issues stated that it was a macro. 
Warnings have also been added about the suppression of a setjmpO macro definition. 

Text describing the accessibility of objects after a longjmp 0 call is added to the DESCRIPTION. 
This text is imported from the entry for longjmp (). 

Text describing the contexts in which calls to setjmp () are valid is moved to the DESCRIPTION 
from the APPLICATION USAGE section. 

The APPLICATION USAGE section is changed to refer to sigsetjmp (). 

Issue 6 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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36425 NAME 

36426 setkey — set encoding key (CRYPT) 

36427 SYNOPSIS 

36428 xsi #include <stdlib.h> 

36429 void setkey (const char *key); 

36430 

36431 DESCRIPTION 

36432 The setkey () function provides (rather primitive) access to an implementation-dependent 

36433 encoding algorithm. The argument of setkey () is an array of length 64 bytes containing only the 

36434 bytes with numerical value of 0 and 1. If this string is divided into groups of 8, the low-order bit 

36435 in each group is ignored; this gives a 56-bit key which is used by the algorithm. This is the key 

36436 that shall be used with the algorithm to encode a string block passed to encrypt (). 

36437 The setkey () function shall not change the setting of errno if successful. An application wishing to 

36438 check for error situations should set errno to 0 before calling setkey(). If errno is non-zero on 

36439 return, an error has occurred. 

36440 The setkey () function need not be reentrant. A function that is not required to be reentrant is not 

36441 required to be thread-safe. 

36442 RETURN VALUE 

36443 No values are returned. 

36444 ERRORS 

36445 The setkey () function shall fail if: 

36446 [ENOSYS] The functionality is not supported on this implementation. 

36447 EXAMPLES 

36448 None. 

36449 APPLICATION USAGE 

36450 Decoding need not be implemented in all environments. This is related to U.S. Government 

36451 restrictions on encryption and decryption routines: the DES decryption algorithm cannot be 

36452 exported outside the U.S. Historical practice has been to ship a different version of the 

36453 encryption library without the decryption feature in the routines supplied. Thus the exported 

36454 version of encrypt () does encoding but not decoding. 

36455 RATIONALE 

36456 None. 

36457 FUTURE DIRECTIONS 

36458 None. 

36459 SEE ALSO 

36460 crypt( ), encrypt( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h> 

36461 CHANGE HISTORY 

36462 First released in Issue 1. 

36463 Derived from Issue 1 of the SVID. 

36464 Issue 4 

36465 The type of argument key is changed from char* to const char*. 

36466 The description of the array is put in terms of bytes instead of characters. 
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36467 The APPLICATION USAGE section is added. 

36468 Issue 5 

36469 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 
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36470 NAME 

36471 setlocale — set program locale 

36472 SYNOPSIS 

36473 tinclude <locale.h> 


36474 char *setlocale (int category, const char * locale) ; 


36475 DESCRIPTION 

36476 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

36477 conflict between the requirements described here and the ISO C standard is unintentional. This 

36478 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 


36479 

36480 

36481 

36482 


The setlocale () function selects the appropriate piece of the program's locale, as specified by the 
category and locale arguments, and may be used to change or query the program's entire locale or 
portions thereof. The value LC_ALL for category names the program's entire locale; other values 
for category name only a part of the program's locale: 


36483 

36484 

36485 


LC_COLLATE Affects the behavior of regular expressions and the collation functions. 

LCJCTYPE Affects the behavior of regular expressions, character classification, character 

conversion functions, and wide-character functions. 


36486 cx LC_MESSAGES Affects what strings are expected by commands and utilities as affirmative or 

36487 negative responses. 


36488 XSI 

36489 


It also affects what strings are given by commands and utilities as affirmative 
or negative responses, and the content of messages. 


36490 


LC_MONETARY Affects the behavior of functions that handle monetary values. 


36491 

36492 


LC_NUMERIC Affects the radix character for the formatted input/output functions and the 
string conversion functions. 


36493 


LC_TIME Affects the behavior of the time conversion functions. 


36494 

36495 

36496 


The locale argument is a pointer to a character string containing the required setting of category. 
The contents of this string are implementation-dependent. In addition, the following preset 
values of locale are defined for all settings of category : 


36497 CX 

36498 

36499 


"POSIX” Specifies the minimal environment for C-language translation called POSIX 

locale. If setlocale () is not invoked, the POSIX locale is the default at entry to I 
main{). I 


36500 "C" 


Same as "POSIX". 


36501 

36502 

36503 

36504 

36505 

36506 


Specifies an implementation-dependent native environment. For XSI- 
conformant systems, this corresponds to the value of the associated 
environment variables, LC_* and LANG; see the System Interface Definitions I 
volume of IEEE Std. 1003.1-200x, Chapter 7, Locale and the System Interface I 
Definitions volume of IEEE Std. 1003.1-200x, Chapter 8, Environment I 
Variables. I 


36507 A null pointer Used to direct setlocale () to query the current internationalized environment 

36508 and return the name of the locale (). 


36509 thr 


The locale state is common to all threads within a process. 
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36510 

36511 

36512 

36513 

36514 

36515 

36516 

36517 

36518 

36519 

36520 

36521 

36522 

36523 

36524 

36525 

36526 

36527 

36528 

36529 

36530 

36531 

36532 

36533 

36534 

36535 

36536 

36537 

36538 

36539 

36540 

36541 

36542 

36543 

36544 

36545 

36546 

36547 


RETURN VALUE 

Upon successful completion, setlocale () shall return the string associated with the specified 
category for the new locale. Otherwise, setlocale( ) shall return a null pointer and the program's 
locale is not changed. 

A null pointer for locale causes setlocale () to return a pointer to the string associated with the 
category for the program's current locale. The program's locale shall not be changed. 

The string returned by setlocale() is such that a subsequent call with that string and its associated 
category shall restore that part of the program's locale. The application shall not modify the string I 
returned which may be overwritten by a subsequent call to setlocale (). I 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

The following code illustrates how a program can initialize the international environment for 
one language, while selectively modifying the program's locale such that regular expressions 
and string operations can be applied to text recorded in a different language: 

setlocale(LC_ALL, "De"); 
setlocale(LC_COLLATE, "Fr@dict"); 

Internationalized programs must call setlocale () to initiate a specific language operation. This can 
be done by calling setlocale () as follows: 

setlocale(LC_ALL, 

Changing the setting of LC_MESSAGES has no effect on catalogs that have already been opened 
by calls to catopen (). 

RATIONALE 

The ISO C standard defines a collection of functions to support internationalization. One of the 
most significant aspects of these functions is a facility to set and query the international 
environment. The international environment is a repository of information that affects the 
behavior of certain functionality, namely: 

1. Character handling 

2. String handling (that is, collating) 

3. Date / time formatting 

4. Numeric editing 

The setlocale () function provides the application developer with the ability to set all or portions, 
called categories, of the international environment. These categories correspond to the areas of 
functionality, mentioned above. The syntax for setlocale () is as follows: 

char *setlocale(int category, const char * locale) ; 

where category is the name of one of five categories, namely: 
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36548 

36549 

36550 

36551 

36552 

36553 

36554 

36555 

36556 

36557 

36558 

36559 

36560 

36561 

36562 

36563 

36564 

36565 

36566 

36567 

36568 

36569 

36570 

36571 

36572 

36573 

36574 

36575 

36576 

36577 

36578 

36579 

36580 

36581 

36582 

36583 

36584 

36585 

36586 

36587 

36588 

36589 

36590 


LC_COLLATE 

LCJCTYPE 

LCJAESSAGES 

LC_MONETARY 

LCJNUMERIC 

LC_TIME 

In addition, a special value called LC_ALL directs setlocale () to set all categories. 

There are two primary uses of setlocale (): 

1. Querying the international environment to find out what it is set to 

2. Setting the international environment, or locale, to a specific value 

The behavior of setlocale () in these two areas is described below. Since it is difficult to describe 
the behavior in words, examples are used to illustrate the behavior of specific uses. 

To query the international environment, setlocale () is invoked with a specific category and the 
NULL pointer as the locale. The NULL pointer is a special directive to setlocale () that tells it to 
query rather than set the international environment. The following syntax is used to query the 
name of the international environment: 

setlocale({LC_ALL, LC_COLLATE, LC_CTYPE, LC_MESSAGES, LC_MONE TARY, \ 

LC_NUMERIC, LC_TIME}, (char *) NULL); 

The setlocale () function shall return the string corresponding to the current international 
environment. This value may be used by a subsequent call to setlocale () to reset the international 
environment to this value. However, it should be noted that the return value from setlocale () is a 
pointer to a static area within the function and is not guaranteed to remain unchanged (that is, it 
may be modified by a subsequent call to setlocale()). Therefore, if the purpose of calling 
setlocale () is to save the value of the current international environment so it can be changed and 
reset later, the return value should be copied to an array of char in the calling program. 

There are three ways to set the international environment with setlocale (): 

setlocale(category , string) 

This usage sets a specific category in the international environment to a specific value 
corresponding to the value of the string. A specific example is provided below: 

setlocale(LC_ALL, "Fr_FR.8859"); 

In this example, all categories of the international environment are set to the locale 
corresponding to the string "Fr_FR. 885 9", or to the French language as spoken in France 
using the ISO/IEC 8859-1:1998 standard codeset. 

If the string does not correspond to a valid locale, setlocale () shall return a NULL pointer 
and the international environment is not changed. Otherwise, setlocale () shall return the 
name of the locale just set. 

setlocale(category" C") 

The ISO C standard states that one locale must exist on all conforming implementations. 
The name of the locale is C and corresponds to a minimal international environment needed 
to support the C programming language. 

setlocale(category ,"") 

This sets a specific category to an implementation-dependent default. For POSIX- 
conforming systems, this corresponds to the value of the environment variables. 
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36591 

36592 

36593 

36594 

36595 

36596 

36597 

36598 

36599 

36600 

36601 

36602 

36603 

36604 

36605 

36606 

36607 

36608 

36609 

36610 

36611 

36612 

36613 

36614 

36615 

36616 

36617 

36618 

36619 

36620 


FUTURE DIRECTIONS 

None. 

SEE ALSO 

exec, isalnum (), isalpha (), iscntrl (), isgraph (), isloiuer (), isprint (), ispunct (), isspace (), isupperi ), 
iswalnum (), iswalpha (), iszvcntrl (), iszvctype (), iswgraph (), iswlower (), isivprint (), iswpunct (), 
iswspace(), iswnpper (), localeconv(), mblen(), mbstowcs {), mbtowc (), nl_langinfo (), printf(), scanf(), 
setlocale (), strcoll (), strerror (), strfmon(), strtod (), strxfrm (), tolozver (), tonpper (), tozvlozver (), 
toivnpper (), wcscoll (), zvcstod (), iucstombs (), wcsxfrm (), zvctomb (), the System Interface Definitions 
volume of IEEE Std. 1003.1-200x, <langinfo.h>, <locale.h> 

CHANGE HISTORY 

First released in Issue 3. 


Issue 4 

The description of LC_MESSAGES is extended to indicate that this category also determines 
what strings are produced by commands and utilities for affirmative and negative responses, 
and that it affects the content of other program messages. This is marked as an extension. 

References to nl_langinfo () are removed. 

The description of the implementation-dependent native locale ("" is clarified by stating the 
related environment variables explicitly. 

The APPLICATION USAGE section is expanded. 

The following changes are incorporated for alignment with the ISO C standard and the 
ISO POSIX-1 standard: 

• The type of the argument locale is changed from char* to const char*. 

• The name "POSIX" is added to the list of standard locale names. 

The following change is incorporated for alignment with the ISO POSIX-2 standard: 

• The LC_MESSAGES value for category is added to the DESCRIPTION. 

Issue 5 

The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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36621 NAME 

36622 setlogmask — set log priority mask 

36623 SYNOPSIS 

36624 xsi #include <syslog.h> 

36625 int setlogmask (int maskpri) ; 

36626 

36627 DESCRIPTION 

36628 Refer to closelog(). 
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36629 NAME 

36630 setnetent — network database function 

36631 SYNOPSIS 

36632 #include <netdb.h> 

36633 void setnetent (int stayopen) ; 

36634 DESCRIPTION 

36635 Refer to endnetent (). 
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36636 NAME 

36637 setpgid — set process group ID for job control 

36638 SYNOPSIS 

36639 #include <unistd.h> 

36640 int setpgid (pid_t pid, pid_t pgid) ; 

36641 DESCRIPTION 

36642 The setpgid() function is used either to join an existing process group or create a new process 

36643 group within the session of the calling process. The process group ID of a session leader shall 

36644 not change. Upon successful completion, the process group ID of the process with a process ID 

36645 that matches pid shall be set to pgid . As a special case, if pid is 0, the process ID of the calling 

36646 process shall be used. Also, if pgid is 0, the process group ID of the indicated process shall be 

36647 used. 

36648 RETURN VALUE 

36649 Upon successful completion, setpgidO shall return 0; otherwise, -1 shall be returned and errno 

36650 shall be set to indicate the error. 

36651 ERRORS 

36652 The setpgid () function shall fail if: 

36653 [EACCES] 

36654 

36655 

36656 [EINVAL] 

36657 

36658 [EPERM] 

36659 [EPERM] 

36660 

36661 

36662 [EPERM] 

36663 

36664 

36665 

36666 [ESRCH] 

36667 

36668 EXAMPLES 

36669 None. 

36670 APPLICATION USAGE 

36671 None. 

36672 RATIONALE 

36673 The setpgid () function is used to group processes together for the purpose of signaling, 

36674 placement in foreground or background, and other job control actions. 

36675 The setpgid () function is similar to the setpgrp( ) function of 4.2 BSD, except that 4.2 BSD allowed 

36676 the specified new process group to assume any value. This presents certain security problems 

36677 and is more flexible than necessary to support job control. 

36678 To provide tighter security, setpgidO on ly allows the calling process to join a process group 

36679 already in use inside its session or create a new process group whose process group ID was 


The value of the pid argument matches the process ID of a child process of the 
calling process and the child process has successfully executed one of the exec 
functions. 

The value of the pgid argument is less than 0, or is not a value supported by 
the implementation. 

The process indicated by the pid argument is a session leader. 

The value of the pid argument matches the process ID of a child process of the 
calling process and the child process is not in the same session as the calling 
process. 

The value of the pgid argument is valid but does not match the process ID of 
the process indicated by the pid argument and there is no process with a 
process group ID that matches the value of the pgid argument in the same 
session as the calling process. 

The value of the pid argument does not match the process ID of the calling 
process or of a child process of the calling process. 


1204 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


setpgidO 


36680 equal to its process ID. 

36681 When a job control shell spawns a new job, the processes in the job must be placed into a new 

36682 process group via setpgidO- There are two timing constraints involved in this action: 

36683 1. The new process must be placed in the new process group before the appropriate program 

36684 is launched via one of the exec functions. 

36685 2. The new process must be placed in the new process group before the shell can correctly 

36686 send signals to the new process group. 

36687 To address these constraints, the following actions are performed. The new processes call 

36688 setpgid() to alter their own process groups after forkO hut before exec. This satisfies the first 

36689 constraint. Under 4.3 BSD, the second constraint is satisfied by the synchronization property of 

36690 vfork( ); that is, the shell is suspended until the child has completed the exec, thus ensuring that 

36691 the child has completed the setpgidO ■ A new version of forkO with this same synchronization 

36692 property was considered, but it was decided instead to merely allow the parent shell process to 

36693 adjust the process group of its child processes via setpgidO- Both timing constraints are now 

36694 satisfied by having both the parent shell and the child attempt to adjust the process group of the 

36695 child process; it does not matter which succeeds first. 

36696 Because it would be confusing to an application to have its process group change after it began 

36697 executing (that is, after exec), and because the child process would already have adjusted its 

36698 process group before this, the [EACCES] error was added to disallow this. 

36699 One non-obvious use of setpgidO is to allow a job control shell to return itself to its original 

36700 process group (the one in effect when the job control shell was executed). A job control shell 

36701 does this before returning control back to its parent when it is terminating or suspending itself as 

36702 a way of restoring its job control "state" back to what its parent would expect. (Note that the 

36703 original process group of the job control shell typically matches the process group of its parent, 

36704 but this is not necessarily always the case.) 

36705 FUTURE DIRECTIONS 

36706 None. 

36707 SEE ALSO 

36708 exec, getpgrpO, setsid (), tcsetpgrpO, the System Interface Definitions volume of 

36709 IEEE Std. 1003.1-200x, <sys/types.h>, <unistd.h> 

36710 CHANGE HISTORY 

36711 First released in Issue 3. 

36712 Entry included for alignment with the POSIX.1-1988 standard. 

36713 Issue 4 

36714 The function is no longer marked as OPTIONAL FUNCTIONALITY. 

36715 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

36716 XSI-conformant systems. 

36717 The <unistd.h> header is added to the SYNOPSIS section. 

36718 The DESCRIPTION in Issue 3 defined the behavior of this function for implementations that 

36719 either supported or did not support job control. As job control is defined as mandatory in Issue 

36720 4, only the former of these is now described. 

36721 The [ENOSYS] error is removed from the ERRORS section. 
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36722 

36723 

36724 

36725 

36726 

36727 

36728 

36729 

36730 


Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 

Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• The setpgid () function is mandatory since _POSIX_JOB_CONTROL is required to be defined 
in this issue. This is a FIPS requirement. 
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36731 NAME 

36732 setpgrp — set process group ID 

36733 SYNOPSIS 

36734 xsi #include <unistd.h> 

36735 pid_t setpgrp (void) ; 

36736 

36737 DESCRIPTION 

36738 If the calling process is not already a session leader, setpgrp () sets the process group ID of the 

36739 calling process to the process ID of the calling process. If setpgrp () creates a new session, then 

36740 the new session has no controlling terminal. 

36741 The setpgrpO function has no effect when the calling process is a session leader. 

36742 RETURN VALUE 

36743 Upon completion, setpgrp () shall return the process group ID. 

36744 ERRORS 

36745 No errors are defined. 

36746 EXAMPLES 

36747 None. 

36748 APPLICATION USAGE 

36749 None. 

36750 RATIONALE 

36751 None. 

36752 FUTURE DIRECTIONS 

36753 None. 

36754 SEE ALSO 

36755 exec, forkO, getpidO, getsidO, kill (), setsid(), the System Interface Definitions volume of 

36756 IEEE Std. 1003.1-200x, <unistd.h> 

36757 CHANGE HISTORY 

36758 First released in Issue 4, Version 2. 

36759 Issue 5 

36760 Moved from X/OPEN UNIX extension to BASE. 
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36761 NAME 

36762 setpriority — set the nice value 

36763 SYNOPSIS 

36764 xsi #include <sys/resource.h> 

36765 int setpriority (int which, id_t who, int nice)} 

36766 

36767 DESCRIPTION 

36768 Refer to getpriority (). 
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36769 NAME 

36770 setprotoent — network protocol database functions 

36771 SYNOPSIS 

36772 #include <netdb.h> 

36773 void setprotoent (int stayopen) ; 

36774 DESCRIPTION 

36775 Refer to en dp ro toen t (). 
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36776 NAME 

36777 setpwent — user database function 

36778 SYNOPSIS 

36779 xsi #include <pwd.h> 

36780 void setpwent (void) ; 

36781 

36782 DESCRIPTION 

36783 Refer to endpzvent (). 
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36784 NAME 

36785 setregid — set real and effective group IDs 

36786 SYNOPSIS 

36787 xsi #include <unistd.h> 

36788 int setregid (gid_t rgid, gid_t egid) ; 

36789 


36790 DESCRIPTION 

36791 The setregid () function is used to set the real and effective group IDs of the calling process. 

36792 If rgid is -1, the real group ID shall not be changed; if egid is -1, the effective group ID shall not 

36793 be changed. 

36794 The real and effective group IDs may be set to different values in the same call. 

36795 Only a process with appropriate privileges can set the real group ID and the effective group ID 

36796 to any valid value. 

36797 A non-privileged process can set either the real group ID to the saved set-group-ID from exec*, 

36798 or the effective group ID to the saved set-group-ID or the real group ID. 

36799 Any supplementary group IDs of the calling process remain unchanged. 

36800 RETURN VALUE 

36801 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 

36802 indicate the error, and neither of the group IDs are changed. 


36803 ERRORS 

36804 The setregid () function shall fail if: 


36805 [EINVAL] 

36806 [EPERM] 

36807 

36808 

36809 

36810 EXAMPLES 

36811 None. 

36812 APPLICATION USAGE 

36813 If a set-group-ID process sets its effective group ID to its real group ID, it can still set its effective 

36814 group ID back to the saved set-group-ID. 

36815 RATIONALE 

36816 None. 

36817 FUTURE DIRECTIONS 

36818 None. 

36819 SEE ALSO 

36820 exec, getidd(), setreuid(), setuid{), the System Interface Definitions volume of 

36821 IEEE Std. 1003.1-200x, <unistd.h> 

36822 CHANGE HISTORY 

36823 First released in Issue 4, Version 2. 


The value of the rgid or egid argument is invalid or out-of-range. 

The process does not have appropriate privileges and a change other than 
changing the real group ID to the saved set-group-ID, or changing the 
effective group ID to the real group ID or the saved set-group-ID, was 
requested. 
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36824 

36825 

36826 

36827 


Issue 5 

Moved from X/OPEN UNIX extension to BASE. 

The DESCRIPTION is updated to indicate that the saved set-group-ID can be set by any of the 
exec* functions, not just execev (). 
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36828 NAME 

36829 setreuid — set real and effective user IDs 

36830 SYNOPSIS 

36831 xsi #include <unistd.h> 

36832 int setreuid (uid_t ruid, uid_t euid) ; 

36833 

36834 DESCRIPTION 

36835 The setreuid( ) function sets the real and effective user IDs of the current process to the values 

36836 specified by the ruid and euid arguments. If ruid or euid is -1, the corresponding effective or real 

36837 user ID of the current process is left unchanged. 

36838 A process with appropriate privileges can set either ID to any value. An unprivileged process 

36839 can only set the effective user ID if the euid argument is equal to either the real, effective, or 

36840 saved user ID of the process. 

36841 It is unspecified whether a process without appropriate privileges is permitted to change the real 

36842 user ID to match the current real, effective, or saved set-user-ID of the process. 

36843 RETURN VALUE 

36844 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 

36845 indicate the error. 


36846 ERRORS 

36847 The setreuid () function shall fail if: 


36848 


[EINVAL] The value of the mid or euid argument is invalid or out-of-range. 


36849 [EPERM] 

36850 

36851 

36852 

36853 EXAMPLES 


The current process does not have appropriate privileges, and either an 
attempt was made to change the effective user ID to a value other than the 
real user ID or the saved set-user-ID or an attempt was made to change the 
real user ID to a value not permitted by the implementation. 


36854 Setting the Effective User ID to the Real User ID 

36855 The following example sets the effective user ID of the calling process to the real user ID, so that 

36856 files created later will be owned by the current user. 

36857 #include <unistd.h> 

36858 #include <sys/types . h> 

36859 

36860 setreuid (getuidO, getuidO); 

36861 

36862 APPLICATION USAGE 

36863 None. 

36864 RATIONALE 

36865 None. 

36866 FUTURE DIRECTIONS 

36867 None. 
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36868 SEE ALSO 

36869 getnid (), setuid (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

36870 CHANGE HISTORY 

36871 First released in Issue 4, Version 2. 

36872 Issue 5 

36873 Moved from X/OPEN UNIX extension to BASE. 
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36874 NAME 

36875 setrlimit — control maximum resource consumption 

36876 SYNOPSIS 

36877 xsi #include <sys/resource . h> 

36878 int setrlimit (int resource , const struct rlimit *rlp) ; 

36879 

36880 DESCRIPTION 

36881 Refer to getrlimit(). 
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36882 NAME 

36883 setservent — network services database functions 

36884 SYNOPSIS 

36885 #include <netdb.h> 

36886 void setservent (int stayopen) ; 

36887 DESCRIPTION 

36888 Refer to endservent(). 
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36889 NAME 

36890 setsid — create session and set process group ID 

36891 SYNOPSIS 

36892 #include <unistd.h> 

36893 pid_t setsid (void) ; 

36894 DESCRIPTION 

36895 The setsid () function creates a new session, if the calling process is not a process group leader. 

36896 Upon return the calling process shall be the session leader of this new session, shall be the 

36897 process group leader of a new process group, and shall have no controlling terminal. The 

36898 process group ID of the calling process shall be set equal to the process ID of the calling process. 

36899 The calling process shall be the only process in the new process group and the only process in 

36900 the new session. 

36901 RETURN VALUE 

36902 Upon successful completion, setsid () shall return the value of the new process group ID of the I 

36903 calling process. Otherwise, it shall return (pid_t)-l and set errno to indicate the error. I 

36904 ERRORS 

36905 The setsid () function shall fail if: 

36906 [EPERM] The calling process is already a process group leader, or the process group ID 

36907 of a process other than the calling process matches the process ID of the 

36908 calling process. 

36909 EXAMPLES 

36910 None. 

36911 APPLICATION USAGE 

36912 None. 

36913 RATIONALE 

36914 The setsid() function is similar to the setpgrp () function of System V. System V, without job 

36915 control, groups processes into process groups and creates new process groups via setpgrp (); only 

36916 one process group may be part of a login session. 

36917 Job control allows multiple process groups within a login session. In order to limit job control 

36918 actions so that they can only affect processes in the same login session, this volume of 

36919 IEEEStd. 1003.1-200x adds the concept of a session that is created via setsid (). The setsid () 

36920 function also creates the initial process group contained in the session. Additional process 

36921 groups can be created via the setpgid( ) function. A System V process group would correspond to 

36922 a POSIX System Interfaces session containing a single POSIX process group. Note that this 

36923 function requires that the calling process not be a process group leader. The usual way to ensure 

36924 this is true is to create a new process with fork () and have it call setsid(). The fork () function 

36925 guarantees that the process ID of the new process does not match any existing process group ID. 

36926 FUTURE DIRECTIONS 

36927 None. 

36928 SEE ALSO 

36929 getsid (), setpgid(), setpgrp (), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

36930 <sys/types.h>, <unistd.h> 
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36931 CHANGE HISTORY 

36932 First released in Issue 3. 

36933 Entry included for alignment with the POSIX.1-1988 standard. 

36934 Issue 4 

36935 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

36936 XSI-conformant systems. 

36937 The <unistd.h> header is added to the SYNOPSIS section. 

36938 The argument list is explicitly defined as void. 

36939 Issue 6 

36940 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

36941 The following new requirements on POSIX implementations derive from alignment with the 

36942 Single UNIX Specification: 

36943 • The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 

36944 required for conforming implementations of previous POSIX specifications, it was not I 

36945 required for UNIX applications. 
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36946 NAME 

36947 setsockopt — set the socket options 

36948 SYNOPSIS 

36949 tinclude <sys/socket. h> 


36950 int setsockopt (int socket, int level, int option_name, 

36951 const void *option_value, socklen_t option_len ) ; 


36952 DESCRIPTION 

36953 The setsockopt () function sets the option specified by the option_name argument, at the protocol 

36954 level specified by the level argument, to the value pointed to by the option_valne argument for the 

36955 socket associated with the file descriptor specified by the socket argument. 

36956 The level argument specifies the protocol level at which the option resides. To set options at the 

36957 socket level, specify the level argument as SOL_SOCKET. To set options at other levels, supply 

36958 the appropriate lecel identifier for the protocol controlling the option. For example, to indicate 

36959 that an option is interpreted by the TCP (Transport Control Protocol), set level to IPPROTO_TCP 

36960 as defined in the <netinet/in.h> header. 

36961 The option_name argument specifies a single option to set. The option_name argument and any 

36962 specified options are passed uninterpreted to the appropriate protocol module for 

36963 interpretations. The <sys/socket.h> header defines the socket-level options. The options are as 

36964 follows: 


36965 SO_DEBUG 

36966 

36967 


Turns on recording of debugging information. This option enables or 
disables debugging in the underlying protocol modules. This option takes 
an int value. This is a Boolean option. 


36968 SO_BROADCAST Permits sending of broadcast messages, if this is supported by the 

36969 protocol. This option takes an int value. This is a Boolean option. 


36970 

36971 

36972 


SO_REUSEADDR Specifies that the rules used in validating addresses supplied to bind() 
should allow reuse of local addresses, if this is supported by the protocol. 
This option takes an int value. This is a Boolean option. 


36973 

36974 

36975 


SO_KEEPALIVE Keeps connections active by enabling the periodic transmission of 
messages, if this is supported by the protocol. This option takes an int 
value. 


36976 

36977 

36978 


If the connected socket fails to respond to these messages, the connection 
is broken and processes writing to that socket are notified with a SIGPIPE 
signal. 


36979 


This is a Boolean option. 


36980 SCLLINGER 

36981 

36982 

36983 

36984 

36985 

36986 

36987 


Lingers on a close () if data is present. This option controls the action 
taken when unsent messages queue on a socket and close () is performed. 
If SCLLINGER is set, the system blocks the process during close () until it 
can transmit the data or until the time expires. If SCLLINGER is not 
specified, and close() is issued, the system handles the call in a way that 
allows the process to continue as quickly as possible. This option takes a 
linger structure, as defined in the <sys/socket.h> header, to specify the 
state of the option and linger interval. 


36988 SO_OOBINLINE Leaves received out-of-band data (data marked urgent) inline. This 

36989 option takes an int value. This is a Boolean option. 
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36990 

36991 

36992 

36993 

36994 

36995 

36996 

36997 

36998 

36999 

37000 

37001 

37002 

37003 

37004 

37005 

37006 

37007 

37008 

37009 

37010 

37011 

37012 

37013 

37014 

37015 

37016 

37017 

37018 

37019 

37020 

37021 

37022 

37023 

37024 

37025 

37026 

37027 

37028 

37029 

37030 

37031 

37032 

37033 

37034 

37035 


SCLSNDBUF 

SCLRCVBUF 

SCLDONTROUTE 


SCLRCVLOWAT 


SCLRCVTIMEO 


SCLSNDLOWAT 


SCLSNDTIMEO 


Sets send buffer size. This option takes an int value. 

Sets receive buffer size. This option takes an int value. 

Requests that outgoing messages bypass the standard routing facilities. 
The destination shall be on a directly-connected network, and messages 
are directed to the appropriate network interface according to the 
destination address. The effect, if any, of this option depends on what 
protocol is in use. This option takes an int value. This is a Boolean option. 

Sets the minimum number of bytes to process for socket input operations. 
The default value for SCLRCVLOWAT is 1. If SO_RCVLOWAT is set to a 
larger value, blocking receive calls normally wait until they have received 
the smaller of the low water mark value or the requested amount. (They 
may return less than the low water mark if an error occurs, a signal is 
caught, or the type of data next in the receive queue is different than that 
returned; for example, out-of-band data.) This option takes an int value. 
Note that not all implementations allow this option to be set. 

Sets the timeout value that specifies the maximum amount of time an 
input function waits until it completes. It accepts a timeval structure with 
the number of seconds and microseconds specifying the limit on how 
long to wait for an input operation to complete. If a receive operation has 
blocked for this much time without receiving additional data, it shall 
return with a partial count or errno set to [EAGAIN] or 
[EWOULDBLOCK] if no data is received. The default for this option is 
zero, which indicates that a receive operation shall not time out. This 
option takes a timeval structure. Note that not all implementations allow 
this option to be set. 

Sets the minimum number of bytes to process for socket output 
operations. Non-blocking output operations shall process no data if flow 
control does not allow the smaller of the send low water mark value or 
the entire request to be processed. This option takes an int value. Note 
that not all implementations allow this option to be set. 

Sets the timeout value specifying the amount of time that an output 
function blocks because flow control prevents data from being sent. If a 
send operation has blocked for this time, it shall return with a partial 
count or with errno set to [EAGAIN] or [EWOULDBLOCK] if no data is 
sent. The default for this option is zero, which indicates that a send 
operation shall not time out. This option stores a timeval structure. Note 
that not all implementations allow this option to be set. 


For Boolean options, 0 indicates that the option is disabled and 1 indicates that the option is 
enabled. 


Options at other protocol levels vary in format and name. 


RETURN VALUE 

Upon successful completion, setsockopt() shall return0. Otherwise, -1 shall be returned and errno 
set to indicate the error. 


ERRORS 

The setsockopt () function shall fail if: 


[EBADF] The socket argument is not a valid file descriptor. 
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37036 [EDOM] The send and receive timeout values are too big to fit into the timeout fields in 

37037 the socket structure. 

37038 [EFAULT] The option_value parameter cannot be accessed or written. 

37039 [EINVAL] The specified option is invalid at the specified socket level or the socket has 

37040 been shut down. 

37041 [EISCONN] The socket is already connected, and a specified option cannot be set while the 

37042 socket is connected. 

37043 [ENOPROTOOPT] 

37044 The option is not supported by the protocol. 

37045 [ENOTSOCK] The socket argument does not refer to a socket. 

37046 The setsockopt { ) function may fail if: 

37047 [ENOMEM] There was insufficient memory available for the operation to complete. 

37048 [ENOBUFS] Insufficient resources are available in the system to complete the call. 

37049 xsr [ENOSR] There were insufficient STREAMS resources available for the operation to 

37050 complete. 

37051 EXAMPLES 

37052 None. 

37053 APPLICATION USAGE 

37054 The setsockopt() function provides an application program with the means to control socket 

37055 behavior. An application program can use setsockopt () to allocate buffer space, control timeouts, 

37056 or permit socket data broadcasts. The <sys/socket.h> header defines the socket-level options 

37057 available to setsockopt (). 

37058 Options may exist at multiple protocol levels. The SO_ options are always present at the 

37059 uppermost socket level. 

37060 RATIONALE 

37061 None. 

37062 FUTURE DIRECTIONS 

37063 None. 

37064 SEE ALSO 

37065 Section 2.10 on page 81, bindO, endprotoentO, getsockoptO, socket (), the System Interface 

37066 Definitions volume of IEEE Std. 1003.1-200x, <netinet/in.h>, <sys/socket.h> 

37067 CHANGE HISTORY 

37068 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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37069 NAME 

37070 setstate — switch pseudorandom number generator state arrays 

37071 SYNOPSIS 

37072 xsi #include <stdlib.h> 

37073 char *setstate (const char * state) ; 

37074 

37075 DESCRIPTION 

37076 Refer to initstate (). 
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37077 NAME 

37078 setuid — set user ID 

37079 SYNOPSIS 

37080 #include <unistd.h> 

37081 int setuid (uid_t uid) ; 

37082 DESCRIPTION 

37083 If the process has appropriate privileges, setnid( ) shall set the real user ID, effective user ID, and 

37084 the saved set-user-ID to uid. 

37085 If the process does not have appropriate privileges, but uid is equal to the real user ID or the 

37086 saved set-user-ID, setuid() shall set the effective user ID to uid ; the real user ID and saved set- 

37087 user-ID shall remain unchanged. 

37088 The setuid( ) function shall not affect the supplementary group list in any way. 

37089 RETURN VALUE 

37090 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 

37091 indicate the error. 

37092 ERRORS 

37093 The setuid() function shall fail, return -1, and set errno to the corresponding value if one or more 

37094 of the following are true: 

37095 [EINVAL] The value of the irid argument is invalid and not supported by the 

37096 implementation. 

37097 [EPERM] The process does not have appropriate privileges and uid does not match the 

37098 real user ID or the saved set-user-ID. 

37099 EXAMPLES 

37100 None. 

37101 APPLICATION USAGE 

37102 None. 

37103 RATIONALE 

37104 The various behaviors of the setuid() and setgid() functions when called by non-privileged 

37105 processes reflect the behavior of different historical implementations. For portability, it is 

37106 recommended that new non-privileged applications use the seteuid() and setegid () functions 

37107 instead. 

37108 The saved set-user-ID capability allows a program to regain the effective user ID established at 

37109 the last exec call. Similarly, the saved set-group-ID capability allows a program to regain the 

37110 effective group ID established at the last exec call. These capabilities are derived from System V. 

37111 Without them, a program might have to run as superuser in order to perform the same 

37112 functions, because superuser can write on the user's files. This is a problem because such a 

37113 program can write on any user's files, and so must be carefully written to emulate the 

37114 permissions of the calling process properly. In System V, these capabilities have traditionally 

37115 been implemented only via the setuid( ) and setgid( ) functions for non-privileged processes. The 

37116 fact that the behavior of those functions was different for privileged processes made them 

37117 difficult to use. The POSIX.1-1990 standard defined the setuid () function to behave differently 

37118 for privileged and unprivileged users. When the caller had the appropriate privilege, the 

37119 function set the calling process's real user ID, effective user ID, and saved set-user ID on 

37120 implementations that supported it. When the caller did not have the appropriate privilege, the 

37121 function set only the effective user ID, subject to permission checks. The former use is generally 

37122 needed for utilities like login and su, which are not portable applications and thus outside the 
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scope of IEEE Std. 1003.1-200x. These utilities wish to change the user ID irrevocably to a new 
value, generally that of an unprivileged user. The latter use is needed for portable applications 
that are installed with the set-user-ID bit and need to perform operations using the real user ID. 

IEEE Std. 1003.1-200x augments the latter functionality with a mandatory feature named 
_POSIX_SAVED_IDS. This feature permits a set-user-ID application to switch its effective user 
ID back and forth between the values of its exec- time real user ID and effective user ID. 
Unfortunately, the POSIX.1-1990 standard did not permit a portable application using this 
feature to work properly when it happened to be executed with the (implementation-dependent) 
appropriate privilege. Furthermore, the application did not even have a means to tell whether it 
had this privilege. Because the saved set-user-ID feature is quite desirable for applications, as 
evidenced by the fact that NIST required it in FIPS 151-2, it has been mandated by 
IEEE Std. 1003.1-200x. However, there are implementors who have been reluctant to support it 
given the limitation described above. 

The 4.3BSD system handles the problem by supporting separate functions: setuid{) (which 
always sets both the real and effective user IDs, like setuid() in IEEE Std. 1003.l-200x for 
privileged users), and seteuid() (which always sets just the effective user ID, like s etuid() in 
IEEE Std. 1003.1-200x for non-privileged users). This separation of functionality into distinct 
functions seems desirable. 4.3BSD does not support the saved set-user-ID feature. It supports 
similar functionality of switching the effective user ID back and forth via setreuid{), which 
permits reversing the real and effective user IDs. This model seems less desirable than the saved 
set-user-ID because the real user ID changes as a side effect. The current 4.4BSD includes saved 
effective IDs and uses them for seteuid () and setegid () as described above. The setreuid() and 
setregid( ) functions will be deprecated or removed. 

The solution here is: 

• Require that all implementations support the functionality of the saved set-user-ID, which is 
set by the exec functions and by privileged calls to setuid (). 

• Add the seteuid() and setegid() functions as portable alternatives to setuid() and setgid() for 
non-privileged and privileged processes. 

Historical systems have provided two mechanisms for a set-user-ID process to change its 
effective user ID to be the same as its real user ID in such a way that it could return to the 
original effective user ID: the use of the setuid() function in the presence of a saved set-user-ID, 
or the use of the BSD s etreuid{) function, which was able to swap the real and effective user IDs. 
The changes included in IEEE Std. 1003.1-200x provide a new mechanism using setenid() in 
conjunction with a saved set-user-ID. Thus, all implementations with the new seteuid () 
mechanism will have a saved set-user-ID for each process, and most of the behavior controlled 
by the _POSIX_SAVED_IDS option has been changed to agree with the case where the option 
was defined. The kill() function is an exception. Implementors of the new seteuid () mechanism 
will generally be required to maintain compatibility with the older mechanisms previously 
supported by their systems. However, compatibility with this use of setreuid () and with the 
_POSIX_SAVED_IDS behavior of kill() is unfortunately complicated. If an implementation with 
a saved set-user-ID allows a process to use setreuid() to swap its real and effective user IDs, but 
were to leave the saved set-user-ID unmodified, the process would then have an effective user 
ID equal to the original real user ID, and both real and saved set-user-ID would be equal to the 
original effective user ID. In that state, the real user would be unable to kill the process, even 
though the effective user ID of the process matches that of the real user, if the kill () behavior of 
_POSIX_SAVED_IDS was used. This is obviously not acceptable. The alternative choice, which is 
used in at least one implementation, is to change the saved set-user-ID to the effective user ID 
during most calls to setreuid(). The standard developers considered that alternative to be less 
correct than the retention of the old behavior of kill() in such systems. Current conforming 
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37172 applications shall accommodate either behavior from kill(), and there appears to be no strong I 

37173 reason for kill () to check the saved set-user-ID rather than the effective user ID. I 

37174 FUTURE DIRECTIONS 

37175 None. 

37176 SEE ALSO 

37177 exec, getenid(), getuid(), setgid (), the System Interface Definitions volume of 

37178 IEEE Std. 1003.1-200x, <sys/types.h>, <unistd.h> 

37179 CHANGE HISTORY 

37180 First released in Issue 1. 

37181 Derived from Issue 1 of the SVID. 

37182 Issue 4 

37183 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

37184 XSI-conformant systems. 

37185 The <unistd.h> header is added to the SYNOPSIS section. 

37186 The following change is incorporated for alignment with the FIPS requirements: 

37187 • All references to the saved set-user-ID are marked as extensions. This is because Issue 4 

37188 defines this mechanism as mandatory, whereas the ISO POSIX-1 standard defines that it is 

37189 only supported if _POSIX_SAVED_IDS is set. 

37190 Issue 6 

37191 In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

37192 The following new requirements on POSIX implementations derive from alignment with the 

37193 Single UNIX Specification: 

37194 • The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 

37195 required for conforming implementations of previous POSIX specifications, it was not 

37196 required for UNIX applications. 

37197 • The functionality associated with _POSIX_SAVED_IDS is now mandatory. This is a FIPS 

37198 requirement. 

37199 The following changes were made to align with the IEEE P1003.1a draft standard: I 

37200 • The effects of setirid( ) in processes without appropriate privileges are changed. 

37201 • A requirement that the supplementary group list is not affected is added. I 
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37202 NAME 

37203 setutxent — reset user accounting database to first entry 

37204 SYNOPSIS 

37205 xsi #include <utmpx.h> 

37206 void setutxent (void) ; 

37207 

37208 DESCRIPTION 

37209 Refer to endittxen t (). 
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37210 NAME 

37211 setvbuf — assign buffering to a stream 

37212 SYNOPSIS 

37213 #include <stdio.h> 

37214 int setvbuf (FILE * stream, char *buf, int type, size_t size) ; 

37215 DESCRIPTION 

37216 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

37217 conflict between the requirements described here and the ISO C standard is unintentional. This I 

37218 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

37219 The setvbuf () function may be used after the stream pointed to by stream is associated with an 

37220 open file but before any other operation is performed on the stream. The argument type 

37221 determines how stream shall be buffered, as follows: 

37222 • {_IOFBF} shall cause input/output to be fully buffered. 

37223 • {_IOLBF} shall cause input/output to be line buffered. 

37224 • {_IONBF} shall cause input/output to be unbuffered. 

37225 If buf is not a null pointer, the array it points to may be used instead of a buffer allocated by 

37226 setvbuf (). The argument size specifies the size of the array. The contents of the array at any time 

37227 are indeterminate. 

37228 For information about streams, see Section 2.5 on page 50. 

37229 RETURN VALUE 

37230 Upon successful completion, setvbuf( ) shall return 0. Otherwise, it shall return a non-zero value 

37231 cx if an invalid value is given for type or if the request cannot be honoured, and may set errno to 

37232 indicate the error. 

37233 ERRORS 

37234 The setvbuf () function may fail if: 

37235 cx [EBADF] The file descriptor underlying stream is not valid. 

37236 EXAMPLES 

37237 None. 

37238 APPLICATION USAGE 

37239 A common source of error is allocating buffer space as an "automatic" variable in a code block, 

37240 and then failing to close the stream in the same block. 

37241 With setvbuf (), allocating a buffer of size bytes does not necessarily imply that all of size bytes are 

37242 used for the buffer area. 

37243 Applications should note that many implementations only provide line buffering on input from 

37244 terminal devices. 

37245 RATIONALE 

37246 None. 

37247 FUTURE DIRECTIONS 

37248 None. 
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37249 

37250 

37251 

37252 

37253 

37254 

37255 

37256 

37257 

37258 

37259 

37260 

37261 


SEE ALSO 

fiopen (), setbnf (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdio.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The second paragraph of the DESCRIPTION is now in Section 2.5 on page 50. 

The [EBADF] error is marked as an extension. 

The APPLICATION USAGE section is expanded. 

The following change is incorporated for alignment with the ISO C standard: 

• This function is no longer marked as an extension. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 
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37262 NAME 

37263 shm_open — open a shared memory object (REALTIME) 

37264 SYNOPSIS 

37265 SHM #include <sys/mman.h> 

37266 int shm_open (const char *name, int of lag, mode_t mode); 

37267 


37268 DESCRIPTION 

37269 The shm_open () function establishes a connection between a shared memory object and a file 

37270 descriptor. It creates an open file description that refers to the shared memory object and a file 

37271 descriptor that refers to that open file description. The file descriptor is used by other functions 

37272 to refer to that shared memory object. The name argument points to a string naming a shared 

37273 memory object. It is unspecified whether the name appears in the file system and is visible to 

37274 other functions that take path names as arguments. The name argument conforms to the 

37275 construction rules for a path name. If name begins with the slash character, then processes calling 

37276 shm_open () with the same value of name refer to the same shared memory object, as long as that 

37277 name has not been removed. If name does not begin with the slash character, the effect is 

37278 implementation-dependent. The interpretation of slash characters other than the leading slash 

37279 character in name is implementation-dependent. 

37280 If successful, shm_open () shall return a file descriptor for the shared memory object that is the 

37281 lowest numbered file descriptor not currently open for that process. The open file description is 

37282 new, and therefore the file descriptor does not share it with any other processes. It is unspecified 

37283 whether the file offset is set. The FD_CLOEXEC file descriptor flag associated with the new file 

37284 descriptor is set. 

37285 The file status flags and file access modes of the open file description are according to the value 

37286 of oflag. The oflag argument is the bitwise-inclusive OR of the following flags defined in the 

37287 header <fcntl.h>. Applications specify exactly one of the first two values (access modes) below 

37288 in the value of oflag: 

37289 0_RD0NLY Open for read access only. 

37290 0_RDWR Open for read or write access. 

37291 Any combination of the remaining flags may be specified in the value of oflag: 


37292 

37293 

37294 

37295 

37296 

37297 

37298 

37299 

37300 

37301 


0_CREAT If the shared memory object exists, this flag has no effect, except as noted 

under 0_EXCL below. Otherwise, the shared memory object is created; the 
user ID of the shared memory object shall be set to the effective user ID of the 
process; the group ID of the shared memory object is set to a system default 
group ID or to the effective group ID of the process. The permission bits of the 
shared memory object shall be set to the value of the mode argument except 
those set in the file mode creation mask of the process. When bits in mode 
other than the file permission bits are set, the effect is unspecified. The mode 
argument does not affect whether the shared memory object is opened for 
reading, for writing, or for both. The shared memory object has a size of zero. 


37302 CLEXCL 

37303 

37304 

37305 

37306 

37307 


If CLEXCL and CLCREAT are set, shm_open() fails if the shared memory 
object exists. The check for the existence of the shared memory object and the 
creation of the object if it does not exist is atomic with respect to other 
processes executing shm_open () naming the same shared memory object with 
CLEXCL and CLCREAT set. If CLEXCL is set and CLCREAT is not set, the 
result is undefined. 
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37308 0_TRUNC If the shared memory object exists, and it is successfully opened 0_RDWR, 

37309 the object shall be truncated to zero length and the mode and owner shall be 

37310 unchanged by this function call. The result of using 0_TRUNC with 

37311 0_RD0NLY is undefined. 

37312 When a shared memory object is created, the state of the shared memory object, including all 

37313 data associated with the shared memory object, persists until the shared memory object is 

37314 unlinked and all other references are gone. It is unspecified whether the name and shared 

37315 memory object state remain valid after a system reboot. 

37316 RETURN VALUE 

37317 Upon successful completion, the shm_open() function shall return a non-negative integer 

37318 representing the lowest numbered unused file descriptor. Otherwise, it shall return -1 and set 

37319 errno to indicate the error. 


37320 ERRORS 

37321 The shm_open () function shall fail if: 


37322 

37323 

37324 

37325 


[EACCES] The shared memory object exists and the permissions specified by oflag are 

denied, or the shared memory object does not exist and permission to create 
the shared memory object is denied, or 0_TRUNC is specified and write 
permission is denied. 


37326 [EEXIST] 0_CREAT and 0_EXCL are set and the named shared memory object already 

37327 exists. 


37328 

37329 

37330 

37331 

37332 

37333 

37334 


[EINTR] The shm_open () operation was interrupted by a signal. 

[EINVAL] The shm_open () operation is not supported for the given name. 

[EMFILE] Too many file descriptors are currently in use by this process. 

[ENAMETOOLONG] 

The length of the name string exceeds {PATH_MAX}, or a path name 
component is longer than {NAME_MAX} while _POSIX_NO_TRUNC is in 
effect. 


37335 

37336 

37337 


[ENFILE] Too many shared memory objects are currently open in the system. 

[ENOENT] CLCREAT is not set and the named shared memory object does not exist. 

[ENOSPC] There is insufficient space for the creation of the new shared memory object. 


37338 EXAMPLES 

37339 None. 

37340 APPLICATION USAGE 

37341 None. 


37342 RATIONALE 

37343 

37344 

37345 

37346 


When the Memory Mapped Files option is supported, the normal open () call is used to obtain a 
descriptor to a file to be mapped according to existing practice with mmap(). When the Shared 
Memory Objects option is supported, the shm_open () function is used to obtain a descriptor to 
the shared memory object to be mapped. 


37347 

37348 

37349 

37350 

37351 


There is ample precedent for having a file descriptor represent several types of objects. In the 
POSIX.1-1990 standard, a file descriptor can represent a file, a pipe, a FIFO, a tty, or a directory. 
Many implementations simply have an operations vector, which is indexed by the file descriptor 
type and does very different operations. Note that in some cases the file descriptor passed to 
generic operations on file descriptors are returned by open() or creat() and in some cases 
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37352 

37353 

37354 

37355 

37356 

37357 

37358 

37359 

37360 

37361 

37362 

37363 

37364 

37365 

37366 

37367 

37368 

37369 

37370 

37371 

37372 

37373 

37374 

37375 

37376 

37377 

37378 

37379 

37380 

37381 

37382 

37383 

37384 

37385 

37386 

37387 

37388 

37389 

37390 

37391 

37392 

37393 

37394 

37395 

37396 

37397 

37398 


returned by alternate functions, such as pipe( ). The latter technique is used by shm_open(). 

Note that such shared memory objects can actually be implemented as mapped files. In both 
cases, the size can be set after the open using /truncate (). The shm_open{ ) function itself does not 
create a shared object of a specified size because this would duplicate an extant function that set 
the size of an object referenced by a file descriptor. 

On implementations where memory objects are implemented using the existing file system, the 
shm_open() function may be implemented using a macro that invokes open(), and the 
shm_unlink() function may be implemented using a macro that invokes unlink (). 

For implementations without a permanent file system, the definition of the name of the memory 
objects is allowed not to survive a system reboot. Note that this allows systems with a 
permanent file system to implement memory objects as data structures internal to the 
implementation as well. 

On implementations that choose to implement memory objects using memory directly, a 
shmjjpen () followed by a /truncate () and close () can be used to preallocate a shared memory 
area and to set the size of that preallocation. This may be necessary for systems without virtual 
memory hardware support in order to ensure that the memory is contiguous. 

The set of valid open flags to shm_open () was restricted to 0_RD0NLY, 0_RDWR, 0_CREAT, 
and 0_TRUNC because these could be easily implemented on most memory mapping systems. 
This volume of IEEE Std. 1003.1-200x is silent on the results if the implementation cannot supply 
the requested file access because of implementation-dependent reasons, including hardware 
ones. 

The error conditions [EACCES] and [ENOTSUP] are provided to inform the application that the 
implementation cannot complete a request. 

[EACCES] indicates for implementation-dependent reasons, probably hardware-related, that the 
implementation cannot comply with a requested mode because it conflicts with another 
requested mode. An example might be that an application desires to open a memory object two 
times, mapping different areas with different access modes. If the implementation cannot map a 
single area into a process space in two places, which would be required if different access modes 
were required for the two areas, then the implementation may inform the application at the time 
of the second open. 

[ENOTSUP] indicates for implementation-dependent reasons, probably hardware-related, that 
the implementation cannot comply with a requested mode at all. An example would be that the 
hardware of the implementation cannot support write-only shared memory areas. 

On all implementations, it may be desirable to restrict the location of the memory objects to 
specific file systems for performance (such as a RAM disk) or implementation-dependent 
reasons (shared memory supported directly only on certain file systems). The shm_open() 
function may be used to enforce these restrictions. There are a number of methods available to 
the application to determine an appropriate name of the file or the location of an appropriate 
directory. One way is from the environment via getenv(). Another would be from a 
configuration file. 

This volume of IEEE Std. 1003.1-200x specifies that memory objects have initial contents of zero 
when created. This is consistent with current behavior for both files and newly allocated 
memory. For those implementations that use physical memory, it would be possible that such 
implementations could simply use available memory and give it to the process uninitialized. 
This, however, is not consistent with standard behavior for the uninitialized data area, the stack, 
and of course, files. Finally, it is highly desirable to set the allocated memory to zero for security 
reasons. Thus, initializing memory objects to zero is required. 
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37399 

37400 

37401 

37402 

37403 

37404 

37405 

37406 

37407 

37408 

37409 

37410 


FUTURE DIRECTIONS 

None. 

SEE ALSO 

close (), dnp(), exec,fcntl(), nimap (), shmat{), slimctl(), shmdt (), shm_unlink (), nmask (), the System 
Interface Definitions volume of IEEE Std. 1003.1-200x, <fcntl.h>, <sys/mman.h> 

CHANGE HISTORY 

First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

Issue 6 

The shm_open() function is marked as part of the _POSIX_SHARED_MEMORY_OBJECTS 
option. 

The [ENOSYS] error condition has been removed as stubs need not be provided if an 
implementation does not support the _POSIX_SHARED_MEMORY_OBJECTS option. 
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37411 NAME 

37412 shm_unlink — remove a shared memory object (REALTIME) 

37413 SYNOPSIS 

37414 SHM #include <sys/mman.h> 

37415 int shm_unlink (const char * name); 

37416 

37417 DESCRIPTION 

37418 The shm_unlink( ) function removes the name of the shared memory object named by the string 

37419 pointed to by name. 

37420 If one or more references to the shared memory object exist when the object is unlinked, the 

37421 name is removed before shm_unlink( ) returns, but the removal of the memory object contents is 

37422 postponed until all open and map references to the shared memory object have been removed. 

37423 Even if the object continues to exist after the last shm_unlink( ), reuse of the name shall cause a 

37424 new shared memory object to be created. 

37425 RETURN VALUE 

37426 Upon successful completion, a value of zero shall be returned. Otherwise, a value of -1 shall be 

37427 returned and errno set to indicate the error. If -1 is returned, the named shared memory object 

37428 shall not be changed by this function call. 

37429 ERRORS 

37430 The shm_nnlink( ) function shall fail if: 

37431 [EACCES] Permission is denied to unlink the named shared memory object. 

37432 [ENAMETOOLONG] 

37433 The length of the name string exceeds |NAME_MAX} while 

37434 _POSIX_NO_TRUNC is in effect. 

37435 [ENOENT] The named shared memory object does not exist. 

37436 EXAMPLES 

37437 None. 

37438 APPLICATION USAGE 

37439 Names of memory objects that were allocated with open() are deleted with unlink( ) in the usual 

37440 fashion. Names of memory objects that were allocated with shm_open () are deleted with 

37441 shm_unlink{). Note that the actual memory object is not destroyed until the last close and 

37442 unmap on it have occurred if it was already in use. 

37443 RATIONALE 

37444 None. 

37445 FUTURE DIRECTIONS 

37446 None. 

37447 SEE ALSO 

37448 close(), mmap(), munmap(), shmat(), shmctl(), shmdt(), shm_open{), the System Interface 

37449 Definitions volume of IEEE Std. 1003.1-200x, <sys/mman.h> 

37450 CHANGE HISTORY 

37451 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 
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37452 

37453 

37454 

37455 

37456 

37457 

37458 


Issue 6 

The shm_unlink() function is marked as part of the _POSIX_SHARED_MEMORY_OBJECTS 
option. 

In the DESCRIPTION, text is added to clarify that reusing the same name after a shmjunlink{) 
will not attach to the old shared memory object. 

The [ENOSYS] error condition has been removed as stubs need not be provided if an 
implementation does not support the _POSIX_SHARED_MEMORY_OBJECTS option. 
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37459 

37460 

37461 

37462 

37463 

37464 

37465 

37466 

37467 

37468 

37469 

37470 

37471 

37472 

37473 

37474 

37475 

37476 

37477 

37478 

37479 

37480 

37481 

37482 

37483 

37484 

37485 

37486 

37487 

37488 

37489 

37490 

37491 

37492 

37493 

37494 

37495 

37496 

37497 

37498 

37499 

37500 

37501 


NAME 

shmat — XSI shared memory attach operation 

SYNOPSIS 

xsi tinclude <sys/shm.h> 

void *shmat(int shmid, const void *shmaddr, int shmflg) ; 


DESCRIPTION 

The shmat () function operates on XSI shared memory (see the System Interface Definitions I 
volume of IEEE Std. 1003.1-200x, Section 3.442, XSI Shared Memory). It is unspecified whether I 
this function interoperates with the realtime interprocess communication facilities defined in 
Section 2.8 on page 59. 

The shmat ( ) function attaches the shared memory segment associated with the shared memory 
identifier specified by shmid to the address space of the calling process. The segment is attached 
at the address specified by one of the following criteria: 

• If shmaddr is a null pointer, the segment is attached at the first available address as selected 
by the system. 

• If shmaddr is not a null pointer and ( shmflg &SHM_RND) is non-zero, the segment is attached 
at the address given by (shmaddr -((uintptr_t)shmaddr %SHMLBA)). The character ' %' is the 
C-language remainder operator. 

• If shmaddr is not a null pointer and ( shmflg &SHM_RND) is 0, the segment is attached at the 
address given by shmaddr. 

• The segment is attached for reading if ( shmflg &SHM_RDONLY) is non-zero and the calling 
process has read permission; otherwise, if it is 0 and the calling process has read and write 
permission, the segment is attached for reading and writing. 

RETURN VALUE 

Upon successful completion, shmat () shall increment the value of shm_nattch in the data 
structure associated with the shared memory ID of the attached shared memory segment and 
return the segment's start address. 

Otherwise, the shared memory segment shall not be attached, shmat( ) shall return -1, and err no 
shall be set to indicate the error. 


ERRORS 

The shmat () function shall fail if: 


[EACCES] Operation permission is denied to the calling process; see Section 2.7 on page 

57. 


[EINVAL] 


[EMFILE] 

[ENOMEM] 


The value of shmid is not a valid shared memory identifier, the shmaddr is not a 
null pointer, and the value of (shmaddr -((uintptr_t)shmaddr %SHMLBA)) is an 
illegal address for attaching shared memory; or the shmaddr is not a null 
pointer, (shmflg &SHM_RND) is 0, and the value of shmaddr is an illegal 
address for attaching shared memory. 

The number of shared memory segments attached to the calling process 
would exceed the system-imposed limit. 

The available data space is not large enough to accommodate the shared 
memory segment. 
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37502 EXAMPLES 

37503 None. 

37504 APPLICATION USAGE 

37505 The POSIX Realtime Extension defines alternative interfaces for interprocess communication. 

37506 Application developers who need to use IPC should design their applications so that modules 

37507 using the IPC routines described in Section 2.7 on page 57 can be easily modified to use the 

37508 alternative interfaces. 

37509 RATIONALE 

37510 None. 

37511 FUTURE DIRECTIONS 

37512 None. 

37513 SEE ALSO 

37514 exec, exit (), fork (), shmctl(), shmdt(), slimget(), shm_open (), shm_unlink( ), the System Interface 

37515 Definitions volume of IEEE Std. 1003.1-200x, <sys/shm.h>. Section 2.7 on page 57 

37516 CHANGE HISTORY 

37517 First released in Issue 2. 

37518 Derived from Issue 2 of the SVID. 

37519 Issue 4 

37520 The function is no longer marked as OPTIONAL FUNCTIONALITY. 

37521 The <sys/types.h> and <sys/ipc.h> headers are removed from the SYNOPSIS section. 

37522 The type of argument shmaddr is changed from char* to const void*. 

37523 The [ENOSYS] error is removed from the ERRORS section. 

37524 The DESCRIPTION is clarified in several places. 

37525 A FUTURE DIRECTIONS section is added warning application developers about migration to 

37526 IEEE 1003.4 interfaces for interprocess communication. 

37527 Issue 5 

37528 Moved from SHARED MEMORY to BASE. 

37529 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 

37530 DIRECTIONS to a new APPLICATION USAGE section. 

37531 Issue 6 

37532 The Open Group corrigenda item U021 /13 has been applied. 
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37572 
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NAME 

shmctl — XSI shared memory control operations 

SYNOPSIS 

xsi tinclude <sys/shm.h> 

int shmctl(int shmid, int cmd, struct shmid_ds *buf) ; 


DESCRIPTION 

The shmctl () function operates on XSI shared memory (see the System Interface Definitions I 
volume of IEEE Std. 1003.1-200x, Section 3.442, XSI Shared Memory). It is unspecified whether I 
this function interoperates with the realtime interprocess communication facilities defined in 
Section 2.8 on page 59. 

The shmctl () function provides a variety of shared memory control operations as specified by 
cmd. The following values for cmd are available: 

IPC_STAT Place the current value of each member of the shmid_ds data structure 

associated with shmid into the structure pointed to by buf. The contents of the 
structure are defined in <sys/shm.h>. 

IPC_SET Set the value of the following members of the shmid_ds data structure 

associated with shmid to the corresponding value found in the structure 
pointed to by buf: 

shm_perm.uid 
shm_perm.gid 

shm_perm. mode Low-order nine bits. 

IPC_SET can only be executed by a process that has an effective user ID equal 
to either that of a process with appropriate privileges or to the value of 
shm_perm.cmd or shm_perm.uid in the shmid_ds data structure associated with 
shmid. 


IPC_RMID Remove the shared memory identifier specified by shmid from the system and 

destroy the shared memory segment and shmid_ds data structure associated 
with it. IPC_RMID can only be executed by a process that has an effective user 
ID equal to either that of a process with appropriate privileges or to the value 
of shm_perm.cmd or shm_perm.uid in the shmid_ds data structure associated 
with shmid. 


RETURN VALUE 

Upon successful completion, shmctl () shall return 0; otherwise, it shall return -1 and set errno to 
indicate the error. 


ERRORS 

The shmctl () function shall fail if: 

[EACCES] The argument cmd is equal to IPC_STAT and the calling process does not have 

read permission; see Section 2.7 on page 57. 

[EINVAL] The value of shmid is not a valid shared memory identifier, or the value of cmd 

is not a valid command. 

[EPERM] The argument cmd is equal to IPC_RMID or IPC_SET and the effective user ID 

of the calling process is not equal to that of a process with appropriate 
privileges and it is not equal to the value of shm_perm.cmd or shmjperm.uid in 
the data structure associated with shmid. 
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37578 The slimctl () function may fail if: 

37579 [EOVERFLOW] The cmd argument is IPC_STAT and the gid or uid value is too large to be 

37580 stored in the structure pointed to by the bnf argument. 

37581 EXAMPLES 

37582 None. 

37583 APPLICATION USAGE 

37584 The POSIX Realtime Extension defines alternative interfaces for interprocess communication. 

37585 Application developers who need to use IPC should design their applications so that modules 

37586 using the IPC routines described in Section 2.7 on page 57 can be easily modified to use the 

37587 alternative interfaces. 

37588 RATIONALE 

37589 None. 

37590 FUTURE DIRECTIONS 

37591 None. 

37592 SEE ALSO 

37593 shmat(), shmdt (), shmget( ), shm_open (), shm_unlink (), the System Interface Definitions volume of 

37594 IEEE Std. 1003.1-200x, <sys/shm.h>, Section 2.7 on page 57 

37595 CHANGE HISTORY 

37596 First released in Issue 2. 

37597 Derived from Issue 2 of the SVID. 

37598 Issue 4 

37599 The function is no longer marked as OPTIONAL FUNCTIONALITY. 

37600 The <sys/types.h> and <sys/ipc.h> headers are removed from the SYNOPSIS section. 

37601 The [ENOSYS] error is removed from the ERRORS section. 

37602 A FUTURE DIRECTIONS section is added warning application developers about migration to 

37603 IEEE 1003.4 interfaces for interprocess communication. 

37604 Issue 4, Version 2 

37605 The ERRORS section is updated for X/OPEN UNIX conformance to include [EOVERFLOW] as 

37606 an optional error. 

37607 Issue 5 

37608 Moved from SHARED MEMORY to BASE. 

37609 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 

37610 DIRECTIONS to a new APPLICATION USAGE section. 
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37611 NAME 

37612 shmdt — XSI shared memory detach operation 

37613 SYNOPSIS 

37614 XSI #include <sys/shm.h> 

37615 int shmdt (const void * shmaddr) ; 

37616 

37617 DESCRIPTION 

37618 The shmdt () function operates on XSI shared memory (see the System Interface Definitions I 

37619 volume of IEEE Std. 1003.1-200x, Section 3.442, XSI Shared Memory). It is unspecified whether I 

37620 this function interoperates with the realtime interprocess communication facilities defined in 

37621 Section 2.8 on page 59. 

37622 The shmdt () function detaches the shared memory segment located at the address specified by 

37623 shmaddr from the address space of the calling process. 

37624 RETURN VALUE 

37625 Upon successful completion, shmdt () shall decrement the value of shm_nattch in the data 

37626 structure associated with the shared memory ID of the attached shared memory segment and 

37627 return 0. 

37628 Otherwise, the shared memory segment shall not be detached, shmdt() shall return -1, and errno 

37629 shall be set to indicate the error. 


37630 ERRORS 

37631 The shmdt () function shall fail if: 


37632 [EINVAL] The value of shmaddr is not the data segment start address of a shared 

37633 memory segment. 


37634 EXAMPLES 

37635 None. 

37636 APPLICATION USAGE 

37637 The POSIX Realtime Extension defines alternative interfaces for interprocess communication. 

37638 Application developers who need to use IPC should design their applications so that modules 

37639 using the IPC routines described in Section 2.7 on page 57 can be easily modified to use the 

37640 alternative interfaces. 

37641 RATIONALE 

37642 None. 

37643 FUTURE DIRECTIONS 

37644 None. 

37645 SEE ALSO 

37646 exec, exit (), fork (), shmat(), shmctl(), shmget(), shm_open(), shm_iinlink{ ), the System Interface 

37647 Definitions volume of IEEE Std. 1003.1-200x, <sys/shm.h>. Section 2.7 on page 57 

37648 CHANGE HISTORY 

37649 First released in Issue 2. 

37650 Derived from Issue 2 of the SVID. 


37651 Issue 4 

37652 The function is no longer marked as OPTIONAL FUNCTIONALITY. 

37653 The <sys/types.h> and <sys/ipc.h> headers are removed from the SYNOPSIS section. 
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37655 

37656 

37657 

37658 

37659 

37660 

37661 

37662 


The type of argument shmaddr is changed from char* to const void*. 

The DESCRIPTION is clarified in several places. 

The [ENOSYS] error is removed from the ERRORS section. 

A FUTURE DIRECTIONS section is added warning application developers about migration to 
IEEE 1003.4 interfaces for interprocess communication. 

Issue 5 

Moved from SHARED MEMORY to BASE. 

The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE 
DIRECTIONS to a new APPLICATION USAGE section. 
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NAME 

shmget — get XSI shared memory segment 

SYNOPSIS 

xsi tinclude <sys/shm.h> 

int shmget(key_t key, size_t size, int shmflg) ; 


DESCRIPTION 

The shmget () function operates on XSI shared memory (see the System Interface Definitions I 
volume of IEEE Std. 1003.1-200x, Section 3.442, XSI Shared Memory). It is unspecified whether I 
this function interoperates with the realtime interprocess communication facilities defined in 
Section 2.8 on page 59. 

The shmget () function shall return the shared memory identifier associated with key. 

A shared memory identifier, associated data structure, and shared memory segment of at least 
size bytes (see <sys/shm.h>) are created for key if one of the following is true: 

• The argument key is equal to IPC_PRIVATE. 

• The argument key does not already have a shared memory identifier associated with it and 
(,shmflg &IPC_CREAT) is non-zero. 

Upon creation, the data structure associated with the new shared memory identifier shall be 
initialized as follows: 


• The values of shmjperm.cuid, shmjperm.uid, shmjperm.cgid, and shmjperm.gid are set equal to 
the effective user ID and effective group ID, respectively, of the calling process. 

• The low-order nine bits of shmyperm.mode are set equal to the low-order nine bits of shmflg. 
The value of shm_segsz is set equal to the value of size. 

• The values of shmjpid, shm_nattch, shm_atime, and shm_dtime are set equal to 0. 

• The value of shm_ctime is set equal to the current time. 

When the shared memory segment is created, it shall be initialized with all zero values. 

RETURN VALUE 

Upon successful completion, shmget () shall return a non-negative integer, namely a shared 
memory identifier; otherwise, it shall return -1 and set errno to indicate the error. 


ERRORS 

The shmget() function shall fail if: 


[EACCES] 


[EEXIST] 

[EINVAL] 


A shared memory identifier exists for key but operation permission as 
specified by the low-order nine bits of shmflg would not be granted; see 
Section 2.7 on page 57. 

A shared memory identifier exists for the argument key but ( shmflg 
&IPC_CREAT) &c&c(shmflg &IPC_EXCL) is non-zero. 

The value of size is less than the system-imposed minimum or greater than the 
system-imposed maximum, or a shared memory identifier exists for the 
argument key but the size of the segment associated with it is less than size and 
size is not 0. 


[ENOENT] A shared memory identifier does not exist for the argument key and ( shmflg 

&IPC_CREAT) is 0. 
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37705 [ENOMEM] 

37706 

37707 

37708 [ENOSPC] 

37709 

37710 

37711 EXAMPLES 

37712 None. 

37713 APPLICATION USAGE 

37714 The POSIX Realtime Extension defines alternative interfaces for interprocess communication. 

37715 Application developers who need to use IPC should design their applications so that modules 

37716 using the IPC routines described in Section 2.7 on page 57 can be easily modified to use the 

37717 alternative interfaces. 

37718 RATIONALE 

37719 None. 

37720 FUTURE DIRECTIONS 

37721 None. 

37722 SEE ALSO 

37723 shmat(), shmctl(), shmdt( ), shm_open(), shm_unlink( ), the System Interface Definitions volume of 

37724 IEEE Std. 1003.1-200x, <sys/shm.h>. Section 2.7 on page 57 

37725 CHANGE HISTORY 

37726 First released in Issue 2. 

37727 Derived from Issue 2 of the SVID. 

37728 Issue 4 

37729 The function is no longer marked as OPTIONAL FUNCTIONALITY. 

37730 The <sys/types.h> and <sys/ipc.h> headers are removed from the SYNOPSIS section. 

37731 The [ENOSYS] error is removed from the ERRORS section. 

37732 A FUTURE DIRECTIONS section is added warning application developers about migration to 

37733 IEEE 1003.4 interfaces for interprocess communication. 

37734 Issue 5 

37735 Moved from SHARED MEMORY to BASE. 

37736 The note about use of POSIX Realtime Extension IPC routines has been moved from FUTURE I 

37737 DIRECTIONS to a new APPLICATION USAGE section. 


A shared memory identifier and associated shared memory segment shall be I 
created, but the amount of available physical memory is not sufficient to fill 
the request. 

A shared memory identifier is to be created, but the system-imposed limit on 
the maximum number of allowed shared memory identifiers system-wide 
would be exceeded. 
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37746 

37747 

37748 
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37769 
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37773 

37774 


NAME 

shutdown — shut down socket send and receive operations 

SYNOPSIS 

#include <sys/socket.h> 

int shutdown(int socket, int how); 

DESCRIPTION 

The shutdown() function shall cause all or part of a full-duplex connection on the socket 
associated with the file descriptor socket to be shut down. 

The shutdown() function takes the following arguments: 

socket Specifies the file descriptor of the socket. 

hozv Specifies the type of shutdown. The values are as follows: 

SHUT_RD Disables further receive operations. 

SHUT_WR Disables further send operations. 

SHUT_RDWR Disables further send and receive operations. 

The shutdoivn() function disables subsequent send and/or receive operations on a socket, 
depending on the value of the hozv argument. 

RETURN VALUE 

Upon successful completion, slmtdozvn() shall return 0; otherwise, -1 shall be returned and errno 
set to indicate the error. 


ERRORS 



The sliutdozvn() 

function shall fail if: 


[EBADF] 

The socket argument is not a valid file descriptor. 


[EINVAL] 

The hozv argument is invalid. 


[ENOTCONN] 

The socket is not connected. 


[ENOTSOCK] 

The socket argument does not refer to a socket. 


The shutdozvn () 

function may fail if: 


[ENOBUFS] 

Insufficient resources were available in the system to perform the operation. 

XSR 

[ENOSR] 

There were insufficient STREAMS resources available for the operation to 
complete. 

EXAMPLES 


None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 
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37776 

37777 

37778 

37779 


SEE ALSO 

getsockopt(), read(), recv{), recvfrom{), recvmsg(), select(), send(), sendto(), setsockopt(), socket(), 
zvrite( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <sys/socket.h> 

CHANGE HISTORY 

First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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37780 NAME 

37781 sigaction — examine and change signal action 

37782 SYNOPSIS 

37783 #include <signal.h> 

37784 int sigaction (int sig, const struct sigaction *act, 

37785 struct sigaction *oact) ; 

37786 DESCRIPTION 

37787 The sigaction () function allows the calling process to examine and/or specify the action to be 

37788 associated with a specific signal. The argument sig specifies the signal; acceptable values are 

37789 defined in <signal.h>. 

37790 The structure sigaction, used to describe an action to be taken, is defined in the header 

37791 <signal.h> to include at least the following members: 

37792 


37793 

Member Type 

Member Name 

Description 

37794 

void(*) (int) 

sajiandler 

SIG_DFL, SIG_IGN, or pointer to a function. 

37795 

sigset_t 

sajnask 

Additional set of signals to be blocked 

37796 

37797 

37798 

int 

sajtags 

during execution of signal-catching 
function. 

Special flags to affect behavior of signal. 

37799 

37800 

void(*) (int, 

siginfo_t *, void *) 

sa_sigaction 

Signal-catching function. 


37801 If the argument act is not a null pointer, it points to a structure specifying the action to be 

37802 associated with the specified signal. If the argument oact is not a null pointer, the action 

37803 previously associated with the signal is stored in the location pointed to by the argument oact. If 

37804 the argument act is a null pointer, signal handling is unchanged; thus, the call can be used to 

37805 enquire about the current handling of a given signal. The SIGKILL and SIGSTOP signals shall 

37806 not be added to the signal mask using this mechanism; this restriction shall be enforced by the 

37807 system without causing an error to be indicated. 

37808 If the SA_SIGINFO flag (see below) is cleared in the sajtags field of the sigaction structure, the 

37809 sajiandler field identifies the action to be associated with the specified signal. If the 

37810 SA_SIGINFO flag is set in the sajtags field, and the implementation supports the Realtime 

37811 Signals Extension option or the X/Open System Interfaces Extension option, the sa_sigaction 

37812 field specifies a signal-catching function. If the SA_SIGINFO bit is cleared and the sajiandler 

37813 field specifies a signal-catching function, or if the SA_SIGINFO bit is set, the sa_mask field 

37814 identifies a set of signals that shall be added to the signal mask of the thread before the signal- 

37815 catching function is invoked. If the sajiandler field specifies a signal-catching function, the 

37816 sajnask field identifies a set of signals that shall be added to the process' signal mask before the 

37817 signal-catching function is invoked. 

37818 The sajtags field can be used to modify the behavior of the specified signal. 

37819 The following flags, defined in the header <signal.h>, can be set in sajtags: 

37820 SA_NOCLDSTOP Do not generate SIGCHLD when children stop. 

37821 xsi SA_ONSTACK If set and an alternate signal stack has been declared with sigaltstack( ) or 

37822 sigstack( ), the signal shall be delivered to the calling process on that stack. 

37823 Otherwise, the signal shall be delivered on the current stack. 

37824 xsi SA_RESETHAND If set, the disposition of the signal shall be reset to SIG_DFL and the 

37825 SA_SIGINFO flag shall be cleared on entry to the signal handler. 
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37827 

37828 

37829 
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37868 

37869 

37870 

37871 


Note: SIGILL and SIGTRAP cannot be automatically reset when 

delivered; the system silently enforces this restriction. 

Otherwise, the disposition of the signal shall not be modified on entry to 
the signal handler. 

In addition, if this flag is set, s igaction () behaves as if the SA_NODEFER 
flag were also set. 

xsi SA_RESTART This flag affects the behavior of interruptible functions; that is, those 

specified to fail with errno set to [EINTR], If set, and a function specified 
as interruptible is interrupted by this signal, the function shall restart and 
shall not fail with [EINTR] unless otherwise specified. If the flag is not 
set, interruptible functions interrupted by this signal shall fail with errno 
set to [EINTR], 

SA_SIGINFO If cleared and the signal is caught, the signal-catching function shall be 

entered as: 

void func(int signo) ; 

where signo is the only argument to the signal catching function. In this 
case, the application shall use the sajmndler member to describe the I 
signal catching function and the application shall not modify the I 
sa_sigaction member. 

xsi i rts If SA_SIGINFO is set and the signal is caught, the signal-catching 

function shall be entered as: 

void func(int signo, siginfo_t *info, void * context ); 

where two additional arguments are passed to the signal catching 
function. The second argument shall point to an object of type siginfo_t 
explaining the reason why the signal was generated; the third argument 
can be cast to a pointer to an object of type ucontext_t to refer to the 
receiving process' context that was interrupted when the signal was I 
delivered. In this case, the application shall use the sa_sigaction member I 
to describe the signal catching function and the application shall not I 
modify the sajmndler member. I 

The si_signo member contains the system-generated signal number. 

xsi The si_errno member may contain implementation-dependent additional 

error information; if non-zero, it contains an error number identifying the 
condition that caused the signal to be generated. 

The si_code member contains a code identifying the cause of the signal. If 
the value of si_code is less than or equal to 0, then the signal was 
generated by a process and si_pid and si_nid, respectively, indicate the 
process ID and the real user ID of the sender. The <signal.h> header 
description contains information about the signal specific contents of the 
elements of the siginfo_t type. 

xsi SA_NOCLDWAIT If set, and sig equals SIGCHLD, child processes of the calling processes 

shall not be transformed into zombie processes when they terminate. If 
the calling process subsequently waits for its children, and the process 
has no unwaited-for children that were transformed into zombie 
processes, it shall block until all of its children terminate, and zvait(), 
zvait3(), zvaitid(), and zvaitpid() shall fail and set errno to [ECHILD], 
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Otherwise, terminating child processes shall be transformed into zombie 
processes, unless SIGCHLD is set to SIG_IGN. 

xsi SA_NODEFER If set and sig is caught, sig shall not be added to the process' signal mask 

on entry to the signal handler unless it is included in sa_mask. Otherwise, 
sig shall always be added to the process' signal mask on entry to the 
signal handler. 

If sig is SIGCHLD and the SA_NOCLDSTOP flag is not set in sajtags , and the implementation 
supports the SIGCHLD signal, then a SIGCHLD signal shall be generated for the calling process 
whenever any of its child processes stop. If sig is SIGCHLD and the SA_NOCLDSTOP flag is set 
in sajtags , then the implementation shall not generate a SIGCHLD signal in this way. 

When a signal is caught by a signal-catching function installed by sigaction (), a new signal mask 
is calculated and installed for the duration of the signal-catching function (or until a call to either 
sigprocmask () or sigsuspend () is made). This mask is formed by taking the union of the current 
xsi signal mask and the value of the sa_mask for the signal being delivered unless SA_NODEFER or 
SA_RESETHAND is set, and then including the signal being delivered. If and when the user's 
signal handler returns normally, the original signal mask is restored. 

Once an action is installed for a specific signal, it remains installed until another action is 
xsi explicitly requested (by another call to sigaction ()), until the SA_RESETHAND flag causes 
resetting of the handler,or until one of the exec functions is called. 

If the previous action for sig had been established by signal (), the values of the fields returned in 
the structure pointed to by oact are unspecified, and in particular oact -^sajiandler is not 
necessarily the same value passed to signal (). However, if a pointer to the same structure or a 
copy thereof is passed to a subsequent call to sigaction () via the act argument, handling of the 
signal shall be as if the original call to signal () were repeated. 

If sigaction () fails, no new signal handler is installed. 

It is unspecified whether an attempt to set the action for a signal that cannot be caught or 
ignored to SIG_DFL is ignored or causes an error to be returned with errno set to [EINVAL]. 

If SA_SIGINFO is not set in sajlags , then the disposition of subsequent occurrences of sig when 
it is already pending is implementation-dependent; the signal-catching function shall be invoked 
rts with a single argument. If the implementation supports the Realtime Signals Extension option, 
and if SA_SIGINFO is set in sajtags, then subsequent occurrences of sig generated by sigqueue( ) 
or as a result of any signal-generating function that supports the specification of an application- 
defined value (when sig is already pending) shall be queued in FIFO order until delivered or 
accepted; the signal-catching function shall be invoked with three arguments. The application 
specified value is passed to the signal-catching function as the si_value member of the siginfo_t 
structure. 

The result of the use of sigaction () and a sigivait( ) function concurrently within a process on the 
same signal is unspecified. 

RETURN VALUE 

Upon successful completion, sigaction () shall return 0; otherwise, -1 shall be returned, errno shall 
be set to indicate the error, and no new signal-catching function shall be installed. 

ERRORS 

The sigaction () function shall fail if: 

[EINVAL] The sig argument is not a valid signal number or an attempt is made to catch a 

signal that cannot be caught or ignore a signal that cannot be ignored. 
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[ENOTSUP] The SA_SIGINFO bit flag is set in the sa_flags field of the sigaction structure, 
and the implementation does not support either the Realtime Signals 
Extension option, or the X/Open System Interfaces Extension option. 

The sigaction () function may fail if: 

[EINVAL] An attempt was made to set the action to SIG_DFL for a signal that cannot be 

caught or ignored (or both). 

EXAMPLES 

None. 

APPLICATION USAGE 

The sigaction () function supersedes the signal () function, and should be used in preference. In 
particular, sigaction () and signal () should not be used in the same process to control the same 
signal. The behavior of reentrant functions, as defined in the DESCRIPTION, is as specified by 
this volume of IEEE Std. 1003.1-200x, regardless of invocation from a signal-catching function. 
This is the only intended meaning of the statement that reentrant functions may be used in 
signal-catching functions without restrictions. Applications must still consider all effects of such 
functions on such things as data structures, files, and process state. In particular, application 
writers need to consider the restrictions on interactions when interrupting sleep () and 
interactions among multiple handles for a file description. The fact that any specific function is 
listed as reentrant does not necessarily mean that invocation of that function from a signal- 
catching function is recommended. 

In order to prevent errors arising from interrupting non-reentrant function calls, applications 
should protect calls to these functions either by blocking the appropriate signals or through the 
use of some programmatic semaphore (see semget (), sem_init( ), sem_open{), and so on). Note in 
particular that even the "safe" functions may modify errno ; the signal-catching function, if not 
executing as an independent thread, may want to save and restore its value. Naturally, the same 
principles apply to the reentrancy of application routines and asynchronous data access. Note 
that longjmp () and siglongjmp () are not in the list of reentrant functions. This is because the code 
executing after longjmp () and siglongjmp () can call any unsafe functions with the same danger as 
calling those unsafe functions directly from the signal handler. Applications that use longjmp () 
and siglongjmp () from within signal handlers require rigorous protection in order to be portable. 
Many of the other functions that are excluded from the list are traditionally implemented using 
either mallocj) or free () functions or the standard I/O library, both of which traditionally use 
data structures in a non-reentrant manner. Because any combination of different functions using 
a common data structure can cause reentrancy problems, this volume of IEEE Std. 1003.1-200x 
does not define the behavior when any unsafe function is called in a signal handler that 
interrupts an unsafe function. 

If the signal occurs other than as the result of calling abort (), kill(), or raise (), the behavior is 
undefined if the signal handler calls any function in the standard library other than one of the 
functions listed in the table above or refers to any object with static storage duration other than 
by assigning a value to a static storage duration variable of type volatile sig_atomic_t. 
Furthermore, if such a call fails, the value of errno is indeterminate. 

Usually, the signal is executed on the stack that was in effect before the signal was delivered. An 
alternate stack may be specified to receive a subset of the signals being caught. 

When the signal handler returns, the receiving process resumes execution at the point it was 
interrupted unless the signal handler makes other arrangements. If longjmp () or _longjmp() is 
used to leave the signal handler, then the signal mask must be explicitly restored by the process. 

this volume of IEEE Std. 1003.1-200x defines the third argument of a signal handling function 
when SA_SIGINFO is set as a void 51 ' instead of a ucontext_t*, but without requiring type 

1248 Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


sigactionO 


37965 

37966 

37967 

37968 

37969 

37970 

37971 

37972 

37973 

37974 

37975 

37976 

37977 

37978 

37979 

37980 

37981 

37982 

37983 

37984 

37985 

37986 

37987 

37988 

37989 

37990 

37991 

37992 

37993 

37994 

37995 

37996 

37997 

37998 

37999 

38000 

38001 

38002 

38003 

38004 

38005 

38006 

38007 

38008 


checking. New applications should explicitly cast the third argument of the signal handling 
function to ucontext_t*. 

The BSD optional four argument signal handling function is not supported by this volume of 
IEEE Std. 1003.1-200x. The BSD declaration would be: 

void handler(int sig, int code, struct sigcontext *scp, 
char *addr); 

where sig is the signal number, code is additional information on certain signals, scp is a pointer 
to the sigcontext structure, and addr is additional address information. Much the same 
information is available in the objects pointed to by the second argument of the signal handler 
specified when SA_SIGINFO is set. 

RATIONALE 

Although this volume of IEEE Std. 1003.1-200x requires that signals that cannot be ignored shall 
not be added to the signal mask when a signal-catching function is entered, there is no explicit 
requirement that subsequent calls to sigaction () reflect this in the information returned in the oact 
argument. In other words, if SIGKILL is included in the sa_nia.sk field of act, it is unspecified 
whether or not a subsequent call to sigaction () returns with SIGKILL included in the sa_mask 
field of oact. 

The SA_NOCLDSTOP flag, when supplied in the act —>sa_flags parameter, allows overloading 
SIGCHLD with the System V semantics that each SIGCLD signal indicates a single terminated 
child. Most portable applications that catch SIGCHLD are expected to install signal-catching 
functions that repeatedly call the zvaitpid () function with the WNOHANG flag set, acting on 
each child for which status is returned, until zvaitpid () returns zero. If stopped children are not of 
interest, the use of the SA_NOCLDSTOP flag can prevent the overhead from invoking the 
signal-catching routine when they stop. 

Some historical implementations also define other mechanisms for stopping processes, such as 
the ptrace() function. These implementations usually do not generate a SIGCHLD signal when 
processes stop due to this mechanism; however, that is beyond the scope of this volume of 
IEEE Std. 1003.1-200x. 

This volume of IEEE Std. 1003.1-200x requires that calls to sigaction () that supply a NULL act 
argument succeed, even in the case of signals that cannot be caught or ignored (that is, SIGKILL 
or SIGSTOP). The System V signal () and BSD s igvec( ) functions return [EINVAL] in these cases 
and, in this respect, their behavior varies from sigaction (). 

This volume of IEEE Std. 1003.1-200x requires that sigaction () properly save and restore a signal 
action set up by the ISO C standard signal () function. However, there is no guarantee that the 
reverse is true, nor could there be given the greater amount of information conveyed by the 
sigaction structure. Because of this, applications should avoid using both functions for the same 
signal in the same process. Since this cannot always be avoided in case of general-purpose 
library routines, they should always be implemented with sigaction (). 

It was intended that the signal () function should be implementable as a library routine using 
sigaction (). 

The POSIX Realtime Extension extends the sigaction () function as specified by the POSIX.1-1990 
standard to allow the application to request on a per-signal basis via an additional signal action 
flag that the extra parameters, including the application-defined signal value, if any, be passed 
to the signal-catching function. 
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FUTURE DIRECTIONS 

The fpathconf( ) function is marked as an extension in the list of safe functions because it is not 
included in the corresponding list in the ISO POSIX-1 standard, but it is expected to be added in 
a future issue. 

SEE ALSO 

Section 2.4 on page 43, bsd_signal(), kiU(), _longjmp{), longjmp{), raise(), semget(), sem_init(), 
sem_open(), sigaddset(), sigaltstack{), sigdelset(), sigemptyset(), sigfiUset(), sigismember(), signal(), 
sigprocmask(), sigsuspend (), ivait(), ivaitid (), luaitpid (), the System Interface Definitions volume 
of IEEE Std. 1003.1-200x, <signal.h>, <ucontext.h> 

CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the POSIX.1-1988 standard. 

Issue 4 

The raise () and signal () functions are added to the list of functions that are either reentrant or not 
interruptible by signals ;fpathconf( ) is also added to this list and marked as an extension; ustat () 
is removed from the list, as this function is withdrawn from the interface definition. It is no 
longer specified whether abort (), exit( ), and longjmp () also fall into this category of functions. 

The APPLICATION USAGE section is added. Most of this text is moved from the 
DESCRIPTION in Issue 3. 

The FUTURE DIRECTIONS section is added. 

The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

• The type of argument act is changed from struct sigaction* to const struct sigaction*. 

• A statement is added to the DESCRIPTION indicating that the consequence of attempting to 
set SIG_DFL for a signal that cannot be caught or ignored is unspecified. The [EINVAL] error, 
describing one possible reaction to this condition, is added to the ERRORS section. 

Issue 4, Version 2 

The following changes are incorporated for X/OPEN UNIX conformance: 

• The DESCRIPTION describes sa_sigaction , the member of the sigaction structure that is the 
signal-catching function. 

. The DESCRIPTION describes the SA_ONSTACK, SA_RESETHAND, SA_RESTART, 
SA_SIGINFO, SA_NOCLDWAIT, and SA_NODEFER settings of sajtags . The text describes 
the implications of the use of SA_SIGINFO for the number of arguments passed to the 
signal-catching function. The text also describes the effects of the SA_NODEFER and 
SA_RESETHAND flags on the delivery of a signal and on the permanence of an installed 
action. 

• The DESCRIPTION specifies the effect if the action for the SIGCHLD signal is set to 
SIG_IGN. 

• In the DESCRIPTION, additional text describes the effect if the action is a pointer to a 
function. A new bullet covers the case where SA_SIGINFO is set. SIGBUS is given as an 
additional signal for which the behavior of a process is undefined following a normal return 
from the signal-catching function. 

• The APPLICATION USAGE section is updated to describe use of an alternate signal stack; 
resumption of the process receiving the signal; coding for compatibility with POSIX.4-1993; 
and implementation of signal-handling functions in BSD. 
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Issue 5 

The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and POSIX 
Threads Extension. 

In the DESCRIPTION, the second argument to func when SA_SIGINFO is set is no longer 
permitted to be NULL, and the description of permitted siginfo_t contents is expanded by 
reference to <signal.h>. 

Because the X/OPEN UNIX Extension functionality is now folded into the BASE, the 
[ENOTSUP] error is deleted. 

Issue 6 

The Open Group corrigenda item U028/7 has been applied. In the paragraph entitled "Signal 
Effects on Other Functions", a reference to sigpending () is added. 

In the DESCRIPTION, the text "Signal Generation and Delivery" is moved to a separate section 
of this volume of IEEE Std. 1003.1-200x. 

Text describing functionality from the Realtime Signals option is marked. 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENOTSUP] error condition is added. 

The DESCRIPTION is updated to avoid use of the term "must" for application requirements. 
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38070 NAME 

38071 sigaddset — add a signal to a signal set 

38072 SYNOPSIS 

38073 #include <signal.h> 

38074 int sigaddset (sigset_t *set, int signo) ; 

38075 DESCRIPTION 

38076 The sigaddset () function adds the individual signal specified by the signo to the signal set pointed 

38077 to by set. 

38078 Applications shall call either sigemptyset() or sigfiUset() at least once for each object of type I 

38079 sigset_t prior to any other use of that object. If such an object is not initialized in this way, but is 

38080 nonetheless supplied as an argument to any of sigaction (), sigaddset (), sigdelset( ), sigismember( ), 

38081 sigpending( ), or sigprocmask( ), the results are undefined. 

38082 RETURN VALUE 

38083 Upon successful completion, sigaddset () shall return 0; otherwise, it shall return -1 and set errno 

38084 to indicate the error. 

38085 ERRORS 

38086 The sigaddset () function may fail if: 

38087 [EINVAL] The value of the signo argument is an invalid or unsupported signal number. 

38088 EXAMPLES 

38089 None. 

38090 APPLICATION USAGE 

38091 None. 

38092 RATIONALE 

38093 None. 

38094 FUTURE DIRECTIONS 

38095 None. 

38096 SEE ALSO 

38097 Section 2.4 on page 43, sigaction (), sigdelset{), sigemptyset{), sigfiUset(), sigismember(), 

38098 sigpending (), sigprocmask (), sigsuspend(), the System Interface Definitions volume of 

38099 IEEE Std. 1003.1-200x, <signal.h> 

38100 CHANGE HISTORY 

38101 First released in Issue 3. 

38102 Entry included for alignment with the POSIX.1-1988 standard. 

38103 Issue 4 

38104 The word "will” is replaced by the word "may" in the ERRORS section. 

38105 Issue 5 

38106 The last paragraph of the DESCRIPTION was included as an APPLICATION USAGE note in 

38107 previous issues. I 

38108 Issue 6 I 

38109 The DESCRIPTION is updated to avoid use of the term "must" for application requirements. I 
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38110 NAME 

38111 sigaltstack — set and get signal alternate stack context 

38112 SYNOPSIS 

38113 xsi tinclude <signal.h> 

38114 int sigaltstack (const stack_t *ss, stack_t *oss) ; 

38115 

38116 DESCRIPTION 

38117 The sigaltstack( ) function allows a process to define and examine the state of an alternate stack 

38118 for signal handlers. Signals that have been explicitly declared to execute on the alternate stack 

38119 shall be delivered on the alternate stack. 

38120 If ss is not a null pointer, it points to a stack_t structure that specifies the alternate signal stack 

38121 that shall take effect upon return from sigaltstack (). The ss_flags member specifies the new stack 

38122 state. If it is set to SS_DISABLE, the stack is disabled and ss_sp and ss_size are ignored. 

38123 Otherwise, the stack shall be enabled, and the ss_sp and ss _size members specify the new address 

38124 and size of the stack. 

38125 The range of addresses starting at s s_sp up to but not including ss_sp+ss_size, is available to the 

38126 implementation for use as the stack. This function makes no assumptions regarding which end 

38127 is the stack base and in which direction the stack grows as items are pushed. 

38128 If oss is not a null pointer, on successful completion it shall point to a stack_t structure that 

38129 specifies the alternate signal stack that was in effect prior to the call to sigaltstack (). The ss_sp 

38130 and ss_size members specify the address and size of that stack. The ss_flags member specifies the 

38131 stack's state, and may contain one of the following values: 

38132 SS_ONSTACK The process is currently executing on the alternate signal stack. Attempts to 

38133 modify the alternate signal stack while the process is executing on it fails. This I 

38134 flag shall not be modified by processes. I 

38135 SS_DISABLE The alternate signal stack is currently disabled. 

38136 The value SIGSTKSZ is a system default specifying the number of bytes that would be used to 

38137 cover the usual case when manually allocating an alternate stack area. The value MINSIGSTKSZ 

38138 is defined to be the minimum stack size for a signal handler. In computing an alternate stack 

38139 size, a program should add that amount to its stack requirements to allow for the system 

38140 implementation overhead. The constants SS_ONSTACK, SS_DISABLE, SIGSTKSZ, and 

38141 MINSIGSTKSZ are defined in <signal.h>. 

38142 After a successful call to one of the exec functions, there are no alternate signal stacks in the new 

38143 process image. 

38144 In some implementations, a signal (whether or not indicated to execute on the alternate stack) 

38145 shall always execute on the alternate stack if it is delivered while another signal is being caught 

38146 using the alternate stack. 

38147 Use of this function by library threads that are not bound to kernel-scheduled entities results in 

38148 undefined behavior. 

38149 RETURN VALUE 

38150 Upon successful completion, sigaltstack( ) shall return 0; otherwise, it shall return -1 and set errno 

38151 to indicate the error. 


System Interfaces, Issue 6 


1253 



sigaltstackO 


System Interfaces 


38152 

38153 

38154 

38155 

38156 

38157 

38158 

38159 

38160 

38161 

38162 

38163 

38164 

38165 

38166 

38167 

38168 

38169 

38170 

38171 

38172 

38173 

38174 

38175 

38176 

38177 

38178 

38179 

38180 

38181 

38182 

38183 

38184 

38185 

38186 

38187 


ERRORS 

The sigaltstack () function shall fail if: 

[EINVAL] The ss argument is not a null pointer, and the ss_flags member pointed to by ss 

contains flags other than SS_DISABLE. 

[ENOMEM] The size of the alternate stack area is less than MINSIGSTKSZ. 

[EPERM] An attempt was made to modify an active stack. 

EXAMPLES 

Allocating Memory for an Alternate Stack 

The following example illustrates a method for allocating memory for an alternate stack. 

#include <signal.h> 

if ((sigstk.ss_sp = malloc(SIGSTKSZ)) == NULL) 

/* Error return. */ 
sigstk.ss_size = SIGSTKSZ; 
sigstk.ss_flags = 0; 

if (sigaltstack(Ssigstk,(stack_t *)0) < 0) 

perror ("sigaltstack"); 

APPLICATION USAGE 

On some implementations, stack space is automatically extended as needed. On those 
implementations, automatic extension is typically not available for an alternate stack. If the stack 
overflows, the behavior is undefined. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

Section 2.4 on page 43, sigaction(), sigsetjmp(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <signal.h> 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 

The last sentence of the DESCRIPTION was included as an APPLICATION USAGE note in 
previous issues. 

Issue 6 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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38188 NAME 

38189 sigdelset — delete a signal from a signal set 

38190 SYNOPSIS 

38191 #include <signal.h> 

38192 int sigdelset (sigset_t *set, int signo) ; 

38193 DESCRIPTION 

38194 The sigdelset() function deletes the individual signal specified by signo from the signal set 

38195 pointed to by set. 

38196 Applications should call either sigemptysetO or sigfillset () at least once for each object of type 

38197 sigset_t prior to any other use of that object. If such an object is not initialized in this way, but is 

38198 nonetheless supplied as an argument to any of sigaction (), sigaddsetO, sigdelset (), sigismember( ), 

38199 sigpending( ), or sigprocmask( ), the results are undefined. 

38200 RETURN VALUE 

38201 Upon successful completion, sigdelsetO shall return 0; otherwise, it shall return -1 and set errno 

38202 to indicate the error. 

38203 ERRORS 

38204 The sigdelset () function may fail if: 

38205 [EINVAL] The signo argument is not a valid signal number, or is an unsupported signal 

38206 number. 

38207 EXAMPLES 

38208 None. 

38209 APPLICATION USAGE 

38210 None. 

38211 RATIONALE 

38212 None. 

38213 FUTURE DIRECTIONS 

38214 None. 

38215 SEE ALSO 

38216 Section 2.4 on page 43, sigaction (), sigaddsetO, sigemptysetO, sigfillset0, sigismemberO, 

38217 sigpending (), sigprocmaskO, sigsuspendO, the System Interface Definitions volume of 

38218 IEEE Std. 1003.1-200x, <signal.h> 

38219 CHANGE HISTORY 

38220 First released in Issue 3. 

38221 Entry included for alignment with the POSIX.1-1988 standard. 

38222 Issue 4 

38223 The word "will” is replaced by the word "may" in the ERRORS section. 

38224 Issue 5 

38225 The last paragraph of the DESCRIPTION was included as an APPLICATION USAGE note in 

38226 previous issues. 
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38227 NAME 

38228 sigemptyset — initialize and empty a signal set 

38229 SYNOPSIS 

38230 #include <signal.h> 

38231 int sigemptyset (sigset_t *set) ; 

38232 DESCRIPTION 

38233 The sigemptyset () function initializes the signal set pointed to by set, such that all signals defined 

38234 in this volume of IEEE Std. 1003.1-200x are excluded. 

38235 RETURN VALUE 

38236 Upon successful completion, sigemptyset() shall return 0; otherwise, it shall return -1 and set 

38237 errno to indicate the error. 

38238 ERRORS 

38239 No errors are defined. 

38240 EXAMPLES 

38241 None. 

38242 APPLICATION USAGE 

38243 None. 

38244 RATIONALE 

38245 The implementation of the sigemptyset () (or sigfillset ()) function could quite trivially clear (or 

38246 set) all the bits in the signal set. Alternatively, it would be reasonable to initialize part of the 

38247 structure, such as a version field, to permit binary-compatibility between releases where the size 

38248 of the set varies. For such reasons, either sigemptyset() or sigfillset () must be called prior to any 

38249 other use of the signal set, even if such use is read-only (for example, as an argument to 

38250 sigpending( )). This function is not intended for dynamic allocation. 

38251 The sigfillset () and sigemptyset () functions require that the resulting signal set include (or 

38252 exclude) all the signals defined in this volume of IEEE Std. 1003.1-200x. Although it is outside 

38253 the scope of this volume of IEEE Std. 1003.1-200x to place this requirement on signals that are 

38254 implemented as extensions, it is recommended that implementation-dependent signals also be 

38255 affected by these functions. However, there may be a good reason for a particular signal not to 

38256 be affected. For example, blocking or ignoring an implementation-dependent signal may have 

38257 undesirable side effects, whereas the default action for that signal is harmless. In such a case, it 

38258 would be preferable for such a signal to be excluded from the signal set returned by sigfillset (). 

38259 In early proposals there was no distinction between invalid and unsupported signals (the names 

38260 of optional signals that were not supported by an implementation were not defined by that 

38261 implementation). The [EINVAL] error was thus specified as a required error for invalid signals. 

38262 With that distinction, it is not necessary to require implementations of these functions to 

38263 determine whether an optional signal is actually supported, as that could have a significant 

38264 performance impact for little value. The error could have been required for invalid signals and 

38265 optional for unsupported signals, but this seemed unnecessarily complex. Thus, the error is 

38266 optional in both cases. 

38267 FUTURE DIRECTIONS 

38268 None. 

38269 SEE ALSO 

38270 Section 2.4 on page 43, sigaction (), sigaddset( ), sigdelset( ), sigfillset (), sigismember( ), sigpending( ), 

38271 sigprocmask (), sigsitspend( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

38272 <signal.h> 
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CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the POSIX.1-1988 standard. 
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38276 NAME 

38277 sigfillset — initialize and fill a signal set 

38278 SYNOPSIS 

38279 #include <signal.h> 

38280 int sigfillset (sigset_t * set) ; 

38281 DESCRIPTION 

38282 The sigfillset() function initializes the signal set pointed to by set, such that all signals defined in 

38283 this volume of IEEE Std. 1003.1-200x are included. 

38284 RETURN VALUE 

38285 Upon successful completion, sigfillsetO shall return 0; otherwise, it shall return -1 and set errno 

38286 to indicate the error. 

38287 ERRORS 

38288 No errors are defined. 

38289 EXAMPLES 

38290 None. 

38291 APPLICATION USAGE 

38292 None. 

38293 RATIONALE 

38294 Refer to sigemptyset( ) on page 1256. 

38295 FUTURE DIRECTIONS 

38296 None. 

38297 SEE ALSO 

38298 Section 2.4 on page 43, sigaction(), sigaddset() r sigdelsetO , sigemptysetO, sigismemberO , 

38299 sigpending (), sigprocmaskO , sigsuspend (), the System Interface Definitions volume of 

38300 IEEE Std. 1003.1-200x, <signal.h> 

38301 CHANGE HISTORY 

38302 First released in Issue 3. 

38303 Entry included for alignment with the POSIX.1-1988 standard. 
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38304 NAME 

38305 sighold, sigignore — add a signal to the signal mask or set a signal disposition to be ignored 

38306 SYNOPSIS 

38307 xsi tinclude <signal.h> 

38308 

38309 

38310 

38311 DESCRIPTION 

38312 Refer to signal (). 


int sighold(int sig) ; 
int sigignore(int sig) ; 


System Interfaces, Issue 6 


1259 




siginterrupt() 


System Interfaces 


38313 NAME 

38314 siginterrupt — allow signals to interrupt functions 

38315 SYNOPSIS 

38316 xsi tinclude <signal.h> 

38317 int siginterrupt (int sig, int flag) ; 

38318 

38319 DESCRIPTION 

38320 The siginterrupt () function is used to change the restart behavior when a function is interrupted 

38321 by the specified signal. The function siginterrupt(sig,flag) has an effect as if implemented as: 

38322 siginterrupt (int sig, int flag) { 

38323 int ret; 

38324 struct sigaction act; 

38325 (void) sigaction (sig, NULL, &act); 

38326 if (flag) 

38327 act. sa_f lags &= ~SA_RESTART; 

38328 else 

38329 act.sa_flags |= SA_RESTART; 

38330 ret = sigaction (sig, &act, NULL); 

38331 return ret; 

38332 } 

38333 RETURN VALUE 

38334 Upon successful completion, siginterrupt() shall return 0; otherwise, -1 shall be returned and 

38335 errno set to indicate the error. 

38336 ERRORS 

38337 The siginterrnpt( ) function shall fail if: 

38338 [EINVAL] The sig argument is not a valid signal number. 

38339 EXAMPLES 

38340 None. 

38341 APPLICATION USAGE 

38342 The siginterrnpt( ) function supports programs written to historical system interfaces. A portable 

38343 application, when being written or rewritten, should use sigaction () with the SA_RESTART flag 

38344 instead of siginterrnpt( ). 

38345 RATIONALE 

38346 None. 

38347 FUTURE DIRECTIONS 

38348 None. 

38349 SEE ALSO 

38350 Section 2.4 on page 43, sigaction (), the System Interface Definitions volume of 

38351 IEEE Std. 1003.1-200x, <signal.h> 

38352 CHANGE HISTORY 

38353 First released in Issue 4, Version 2. 
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38354 Issue 5 

38355 Moved from X/OPEN UNIX extension to BASE. 
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38356 NAME 

38357 sigismember — test for a signal in a signal set 

38358 SYNOPSIS 

38359 #include <signal.h> 

38360 int sigismember (const sigset_t *set, int signo) ; 

38361 DESCRIPTION 

38362 The sigismember () function tests whether the signal specified by signo is a member of the set 

38363 pointed to by set. 

38364 Applications should call either sigemptyset() or sigfillset() at least once for each object of type 

38365 sigset_t prior to any other use of that object. If such an object is not initialized in this way, but is 

38366 nonetheless supplied as an argument to any of sigaction (), sigaddset(), sigdelset( ), sigismember (), 

38367 sigpending( ), or sigprocmask( ), the results are undefined. 

38368 RETURN VALUE 

38369 Upon successful completion, sigismember() shall return 1 if the specified signal is a member of 

38370 the specified set, or 0 if it is not. Otherwise, it shall return -1 and set errno to indicate the error. 

38371 ERRORS 

38372 The sigismember () function may fail if: 

38373 [EINVAL] The signo argument is not a valid signal number, or is an unsupported signal 

38374 number. 

38375 EXAMPLES 

38376 None. 

38377 APPLICATION USAGE 

38378 None. 

38379 RATIONALE 

38380 None. 

38381 FUTURE DIRECTIONS 

38382 None. 

38383 SEE ALSO 

38384 Section 2.4 on page 43, sigaction (), sigaddset{), sigdelset( ), sigfillset(), sigemptyset( ), sigpending( ), 

38385 sigprocmask(), sigsuspend (), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

38386 <signal.h> 

38387 CHANGE HISTORY 

38388 First released in Issue 3. 

38389 Entry included for alignment with the POSIX.1-1988 standard. 

38390 Issue 4 

38391 The following changes are incorporated for alignment with the ISO C standard: 

38392 • The type of the argument set is changed from sigset_t* to type const sigset_t*. 

38393 • The word "will" is replaced by the word "may" in the ERRORS section. 

38394 Issue 5 

38395 The last paragraph of the DESCRIPTION was included as an APPLICATION USAGE note in 

38396 previous issues. 
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NAME 

siglongjmp — non-local goto with signal handling 

SYNOPSIS 

#include <setjmp.h> 

void siglongjmp(sigjmp_buf env, int val) ; 

DESCRIPTION 

The siglongjmp () function restores the environment saved by the most recent invocation of 
sigsetjmp () in the same thread, with the corresponding sigjmpjbuf argument. If there is no such 
invocation, or if the function containing the invocation of sigsetjmp () has terminated execution in 
the interim, the behavior is undefined. 

All accessible objects have values as of the time sigsetjmp () was called, except that the values of 
objects of automatic storage duration which are local to the function containing the invocation of 
the corresponding sigsetjmp () which do not have volatile-qualified type and which are changed 
between the sigsetjmp () invocation and siglongjmpO call are indeterminate. 

As it bypasses the usual function call and return mechanisms, siglongjmpO shall execute 
correctly in contexts of interrupts, signals, and any of their associated functions. However, if 
siglongjmp () is invoked from a nested signal handler (that is, from a function invoked as a result 
of a signal raised during the handling of another signal), the behavior is undefined. 

The siglongjmp () function shall restore the saved signal mask if and only if the env argument was 
initialized by a call to sigsetjmp () with a non-zero savemask argument. 

The effect of a call to siglongjmp () where initialization of the jmpjbuf structure was not 
performed in the calling thread is undefined. 

RETURN VALUE 

After siglongjmpO is completed, program execution shall continue as if the corresponding 
invocation of sigsetjmp () had just returned the value specified by val . The siglongjmp () function 
shall not cause sigsetjmpO to return 0; if val is 0, sigsetjmp () shall return the value 1. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

The distinction between setjmpO or longjmpO and sigsetjmp () or siglongjmpO is only significant 
for programs which use sigaction (), sigprocmaskj ), or sigsnspendj ). 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

longjmpO , setjmpO , sigprocmaskO, sigsetjmpO , sigsuspend (), the System Interface Definitions 
volume of IEEE Std. 1003.1-200x, <setjmp.h> 

CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the ISO POSIX-1 standard. 
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38440 Issue 4 

38441 The APPLICATION USAGE section is amended. 

38442 An ERRORS section is added. 

38443 Issue 5 

38444 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 
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38445 NAME 

38446 sighold, sigignore, signal, sigpause, sigrelse, sigset — signal management 

38447 SYNOPSIS 

38448 #include <signal.h> 

38449 void (*signal(int sig, void ( * func ) ( int ) ) ) (int); 

38450 xsi int sighold (int sig); 

38451 int sigignore (int sig) ; 

38452 int sigpause (int sig) ; 

38453 int sigrelse (int sig) ; 

38454 void (*sigset(int sig, void ( *disp) (int))) (int); 

38455 

38456 DESCRIPTION 

38457 cx For signal (): The functionality described on this reference page is aligned with the ISOC 

38458 standard. Any conflict between the requirements described here and the ISO C standard is I 

38459 unintentional. This volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

38460 cx Use of any of these functions is unspecified in a multi-threaded process. 

38461 The signal () function chooses one of three ways in which receipt of the signal number sig is to be 

38462 subsequently handled. If the value of func is SIG_DFL, default handling for that signal shall 

38463 occur. If the value of func is SIG_IGN, the signal shall be ignored. Otherwise, the application I 

38464 shall ensure that func points to a function to be called when that signal occurs. Such a function is I 

38465 called a signal handler. 

38466 When a signal occurs, if func points to a function, first the equivalent of a: 

38467 signal {sig, SIG_DFL) ; 

38468 is executed or an implementation-dependent blocking of the signal is performed. (If the value of 

38469 sig is SIGILL, whether the reset to SIG_DFL occurs is implementation-dependent.) Next the 

38470 equivalent of: 

38471 (*func) (sig) ; 

38472 is executed. The func function may terminate by executing a return statement or by calling 

38473 abort (), exit( ), or longjmpi). It func executes a return statement and the value of sig was SIGFPE 

38474 or any other implementation-dependent value corresponding to a computational exception, the 

38475 behavior is undefined. Otherwise, the program shall resume execution at the point it was 

38476 interrupted. 

38477 If the signal occurs other than as the result of calling abort (), kill (), or raise( ), the behavior is 

38478 undefined if the signal handler calls any function in the standard library other than one of the 

38479 functions listed on the sigaction() reference page or refers to any object with static storage 

38480 duration other than by assigning a value to a static storage duration variable of type volatile 

38481 sig_atomic_t. Furthermore, if such a call fails, the value of errno is indeterminate. 

38482 At program start-up, the equivalent of: I 

38483 signal (sig, SIG_IGN) ; 

38484 is executed for some signals, and the equivalent of: 

38485 signal (sig, SIG_DFL) ; 

38486 is executed for all other signals (see exec). 

38487 xsi The sighold(), sigignore{), sigpause{), sigrelse(), and sigset () functions provide simplified signal 

38488 management. 
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The sigset( ) function is used to modify signal dispositions. The sig argument specifies the signal, 
which may be any signal except SIGKILL and SIGSTOP. The disp argument specifies the signal's 
disposition, which may be SIG_DFL, SIG_IGN, or the address of a signal handler. If sigset() is 
used, and disp is the address of a signal handler, the system shall add sig to the calling process' 
signal mask before executing the signal handler; when the signal handler returns, the system 
shall restore the calling process' signal mask to its state prior the delivery of the signal. In 
addition, if sigset() is used, and disp is equal to SIG_HOLD, sig shall be added to the calling 
process' signal mask and sig' s disposition shall remain unchanged. If sigset( ) is used, and disp is 
not equal to SIG_HOLD, sig shall be removed from the calling process' signal mask. 

The sighold () function adds sig to the calling process' signal mask. 

The sigrelse( ) function removes sig from the calling process' signal mask. 

The sigignore{ ) function sets the disposition of sig to SIG_IGN. 

The sigpause () function removes sig from the calling process' signal mask and suspends the 
calling process until a signal is received. The sigpause{) function restores the process' signal 
mask to its original state before returning. 

If the action for the SIGCHLD signal is set to SIG_IGN, child processes of the calling processes 
shall not be transformed into zombie processes when they terminate. If the calling process 
subsequently waits for its children, and the process has no unwaited-for children that were 
transformed into zombie processes, it shall block until all of its children terminate, and zvait(), 
waits (), zvaitid (), and zvaitpid () shall fail and set errno to [ECHILD], 

RETURN VALUE 

If the request can be honoured, signal () shall return the value of fine for the most recent call to 
signal () for the specified signal sig. Otherwise, SIG_ERR shall be returned and a positive value 
shall be stored in errno. 

xsi Upon successful completion, sigset( ) shall return SIG_HOLD if the signal had been blocked and 
the signal's previous disposition if it had not been blocked. Otherwise, SIG_ERR shall be 
returned and errno set to indicate the error. 

The sigpanse{) function shall suspend execution of the thread until a signal is received, 
whereupon it shall return -1 and set errno to [EINTR], 

For all other functions, upon successful completion, 0 shall be returned. Otherwise, -1 shall be 
returned and errno set to indicate the error. 

ERRORS 

The signal () function shall fail if: 

cx [EINVAL] The sig argument is not a valid signal number or an attempt is made to catch a 

signal that cannot be caught or ignore a signal that cannot be ignored. 

The signal () function may fail if: 

cx [EINVAL] An attempt was made to set the action to SIG_DFL for a signal that cannot be 

caught or ignored (or both). 

The sighold(), sigignore( ), sigpanse (), sigrelse( ), and s igset( ) functions shall fail if: 
xsi [EINVAL] The sig argument is an illegal signal number. 

The sigset () and sigignore( ) functions shall fail if: 

xsi [EINVAL] An attempt is made to catch a signal that cannot be caught, or to ignore a 

signal that cannot be ignored. 
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EXAMPLES 

None. 

APPLICATION USAGE 

The sigaction () function provides a more comprehensive and reliable mechanism for controlling 
signals; new applications should use sigaction () rather than signal (). 

The sighold() function, in conjunction with sigrelse() or sigpause(), may be used to establish 
critical regions of code that require the delivery of a signal to be temporarily deferred. 

The sigsuspend() function should be used in preference to sigpause( ) for broader portability. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

Section 2.4 on page 43, exec, pause{), sigaction (), sigsuspend(), waitid(), the System Interface 
Definitions volume of IEEE Std. 1003.1-200x, <signal.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The APPLICATION USAGE section is added. 

The following changes are incorporated for alignment with the ISO C standard: 

• The function is no longer marked as an extension. 

• The argument int is added to the definition offline in the SYNOPSIS section. 

• In Issue 3, this function cross-referred to sigaction (). This issue provides a complete 
description of the function as defined in ISO C standard. 

Issue 4, Version 2 

The following changes are incorporated for X/OPEN UNIX conformance: 

• The sighold{), sigignore{), sigpause(), sigrelse{), and sigset() functions are added to the 
SYNOPSIS. 

• The DESCRIPTION is updated to describe semantics of the above functions. 

• Additional text is added to the RETURN VALUE section to describe possible returns from 
the sigset( ) function specifically, and all of the above functions in general. 

• The ERRORS section is restructured to describe possible error returns from each of the above 
functions individually. 

• The APPLICATION USAGE section is updated to describe certain programming 
considerations associated with the X/OPEN UNIX functions. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 

The DESCRIPTION is updated to indicate that the sigpause() function restores the process' 
signal mask to its original state before returning. 
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38574 

38575 

38576 

38577 


The RETURN VALUE section is updated to indicate that the sigpanse() function suspends 
execution of the process until a signal is received, whereupon it returns -1 and sets errno to 
[EINTR]. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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38578 NAME 

38579 sigpause — remove a signal from the signal mask and suspend the thread 

38580 SYNOPSIS 

38581 xsi #include <signal.h> 

38582 int sigpause (int sig) ; 

38583 

38584 DESCRIPTION 

38585 Refer to signal (). 
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38586 NAME 

38587 sigpending — examine pending signals 

38588 SYNOPSIS 

38589 #include <signal.h> 

38590 int sigpending (sigset_t * set) ; 

38591 DESCRIPTION 

38592 The sigpending () function stores, in the location referenced by the set argument, the set of signals 

38593 that are blocked from delivery to the calling thread and that are pending on the process or the 

38594 calling thread. 

38595 RETURN VALUE 

38596 Upon successful completion, sigpendingO shall return 0; otherwise, -1 shall be returned and 

38597 errno set to indicate the error. 

38598 ERRORS 

38599 No errors are defined. 

38600 EXAMPLES 

38601 None. 

38602 APPLICATION USAGE 

38603 None. 

38604 RATIONALE 

38605 None. 

38606 FUTURE DIRECTIONS 

38607 None. 

38608 SEE ALSO 

38609 sigaddset (), sigdelset (), sigeniptyset (), sigfillset (), sigismember (), sigprocmask ( ), the System Interface 

38610 Definitions volume of IEEE Std. 1003.1-200x, <signal.h> 

38611 CHANGE HISTORY 

38612 First released in Issue 3. 

38613 Issue 5 

38614 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 
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38615 NAME 

38616 sigprocmask — examine and change blocked signals 

38617 SYNOPSIS 

38618 #include <signal.h> 

38619 int sigprocmask (int how, const sigset_t *set, sigset_t 

38620 DESCRIPTION 

38621 Refer to pthread_sigmask (). 


*oset) ; 
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NAME 

sigqueue — queue a signal to a process (REALTIME) 

SYNOPSIS 

rts tinclude <signal.h> 

int sigqueue(pid_t pid, int signo, const union sigval value) ; 


DESCRIPTION 

The sigqueue() function shall cause the signal specified by signo to be sent with the value 
specified by value to the process specified by pid. If signo is zero (the null signal), error checking 
is performed but no signal is actually sent. The null signal can be used to check the validity of 
pid. 

The conditions required for a process to have permission to queue a signal to another process 
are the same as for the kill () function. 

The sigqueue( ) function returns immediately. If SA_SIGINFO is set for signo and if the resources 
were available to queue the signal, the signal is queued and sent to the receiving process. If 
SA_SIGINFO is not set for signo, then signo is sent at least once to the receiving process; it is 
unspecified whether value shall be sent to the receiving process as a result of this call. 

If the value of pid causes signo to be generated for the sending process, and if signo is not blocked 
for the calling thread and if no other thread has signo unblocked or is waiting in a sigwait{) 
function for signo, either signo or at least the pending, unblocked signal shall be delivered to the 
calling thread before the sigqueue () function returns. Should any multiple pending signals in the 
range SIGRTMIN to SIGRTMAX be selected for delivery, it shall be the lowest numbered one. 
The selection order between realtime and non-realtime signals, or between multiple pending 
non-realtime signals, is unspecified. 

RETURN VALUE 

Upon successful completion, the specified signal shall have been queued, and the sigqueue() 
function shall return a value of zero. Otherwise, the function shall return a value of -1 and set 
errno to indicate the error. 


ERRORS 

The sigqueue( ) function shall fail if: 

[EAGAIN] No resources available to queue the signal. The process has already queued 

SIGQUEUE_MAX signals that are still pending at the receiver(s), or a system- 
wide resource limit has been exceeded. 


[EINVAL] 

[EPERM] 

[ESRCH] 


The value of the signo argument is an invalid or unsupported signal number. 

The process does not have the appropriate privilege to send the signal to the 
receiving process. 

The process pid does not exist. 
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38659 EXAMPLES 

38660 None. 

38661 APPLICATION USAGE 

38662 None. 

38663 RATIONALE 

38664 The sigqueue () function allows an application to queue a realtime signal to itself or to another 

38665 process, specifying the application-defined value. This is common practice in realtime 

38666 applications on existing realtime systems. It was felt that specifying another function in the 

38667 sig... name space already carved out for signals was preferable to extending the function to 

38668 kill(). 

38669 Such a function became necessary when the put /get event function of the message queues was 

38670 removed. It should be noted that the sigqiteue () function implies reduced performance in a 

38671 security-conscious implementation as the access permissions between the sender and receiver 

38672 have to be checked on each send when the pid is resolved into a target process. Such access 

38673 checks were necessary only at message queue open in the previous function. 

38674 The standard developers required that sigqnene( ) have the same semantics with respect to the 

38675 null signal as kill (), and that the same permission checking be used. But because of the difficulty 

38676 of implementing the "broadcast” semantic of kiU() (for example, to process groups) and the 

38677 interaction with resource allocation, this semantic was not adopted. The sigqiteite() function 

38678 queues a signal to a single process specified by the pid argument. 

38679 The sigqneue( ) function can fail if the system has insufficient resources to queue the signal. An 

38680 explicit limit on the number of queued signals that a process could send was introduced. While 

38681 the limit is "per-sender", this volume of IEEE Std. 1003.1-200x does not specify that the 

38682 resources be part of the state of the sender. This would require either that the sender be 

38683 maintained after exit until all signals that it had sent to other processes were handled or that all 

38684 such signals that had not yet been acted upon be removed from the queue(s) of the receivers. 

38685 This volume of IEEE Std. 1003.1-200x does not preclude this behavior, but an implementation 

38686 that allocated queuing resources from a system-wide pool (with per-sender limits) and that 

38687 leaves queued signals pending after the sender exits is also permitted. 

38688 FUTURE DIRECTIONS 

38689 None. 

38690 SEE ALSO 

38691 Section 2.8.1 on page 59, the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

38692 <signal.h> 

38693 CHANGE HISTORY 

38694 First released in Issue 5. Included for alignment with the POSIX Realtime Extension and the I 

38695 POSIX Threads Extension. I 


38696 Issue 6 

38697 The sigqueue () function is marked as part of the _POSIX_REALTIME_SIGNALS option. 


38698 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

38699 implementation does not support the _POSIX_REALTIME_SIGNALS option. 
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38700 NAME 

38701 sigrelse, sigset — remove a signal from signal mask or modify signal disposition 

38702 SYNOPSIS 

38703 xsi tinclude <signal.h> 

38704 

38705 

38706 

38707 DESCRIPTION 

38708 Refer to signal (). 


int sigrelse(int sig) ; 

void (*sigset(int sig, void ( *disp ) (int))) (int); 
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38709 NAME 

38710 sigsetjmp — set jump point for a non-local goto 

38711 SYNOPSIS 

38712 #include <setjmp.h> 

38713 int sigset jmp (sig jmp_buf env, int savemask) ; 

38714 DESCRIPTION 

38715 A call to sigsetjmpO saves the calling environment in its env argument for later use by 

38716 siglongjmpO ■ It is unspecified whether sigsetjmpO is a macro or a function. If a macro definition 

38717 is suppressed in order to access an actual function, or a program defines an external identifier 

38718 with the name sigsetjmp, the behavior is undefined. 

38719 If the value of the savemask argument is not 0, sigsetjmp () shall also save the current signal mask 

38720 of the calling thread as part of the calling environment. 

38721 All accessible objects have values as of the time siglongjmp () was called, except that the values of 

38722 objects of automatic storage duration which are local to the function containing the invocation of 

38723 the corresponding sigsetjmp () which do not have volatile-qualified type and which are changed 

38724 between the sigsetjmp () invocation and siglongjmp () call are indeterminate. 

38725 The application shall ensure that an invocation of sigsetjmpO appears in one of the following I 

38726 contexts only: I 

38727 • The entire controlling expression of a selection or iteration statement 

38728 • One operand of a relational or equality operator with the other operand an integral constant 

38729 expression, with the resulting expression being the entire controlling expression of a 

38730 selection or iteration statement 

38731 • The operand of a unary (' !') operator with the resulting expression being the entire 

38732 controlling expression of a selection or iteration 

38733 • The entire expression of an expression statement (possibly cast to void) 

38734 RETURN VALUE 

38735 If the return is from a successful direct invocation, sigsetjmp () shall return 0. If the return is from 

38736 a call to siglongjmp (), sigsetjmp () shall return a non-zero value. 

38737 ERRORS 

38738 No errors are defined. 

38739 EXAMPLES 

38740 None. 

38741 APPLICATION USAGE 

38742 The distinction between setjmpO/longjmpO and sigsetjmpO /siglongjmpO is only significant for 

38743 programs which use sigaction (), sigprocmaskj ), or sigsnspendj ). 

38744 RATIONALE 

38745 The ISO C standard specifies various restrictions on the usage of the setjmp () macro in order to 

38746 permit implementors to recognize the name in the compiler and not implement an actual 

38747 function. These same restrictions apply to the sigsetjmpO macro. 

38748 There are processors that cannot easily support these calls, but this was not considered a 

38749 sufficient reason to exclude them. 

38750 4.2 BSD and 4.3 BSD systems provide functions named _setjmp () and Jongjmp () that, together 

38751 with setjmp 0 and long jmp (), provide the same functionality as sigsetjmp () and siglongjmpO ■ On 

38752 those systems, setjmp 0 and longjmpO save and restore signal masks, while _setjmpO and 
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Jongjmp () do not. On System V, Release 3 and in corresponding issues of the SVID, setjmp () and 
longjmp () are explicitly defined not to save and restore signal masks. In order to permit existing 
practice in both cases, the relation of setjmp () and longjmp () to signal masks is not specified, and 
a new set of functions is defined instead. 

The longjmp () and siglongjmp () functions operate as in the previous issue provided the matching 
setjmp () or sigsetjmpO has been performed in the same thread. Non-local jumps into contexts 
saved by other threads would be at best a questionable practice and were not considered worthy 
of standardization. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

siglongjmp (), signal (), sigprocmaskj ), sigsuspendO, the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <setjmp.h> 

CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the POSIX.1-1988 standard. 

Issue 4 

The DESCRIPTION states that sigsetjmp () is a macro or a function. Issue 3 states that it is a 
macro. Warnings are also added about the suppression of a sigsetjmp () macro definition. 

A statement is added to the DESCRIPTION about the accessibility of objects after a siglongjmp () 
call. 

Text is added to the DESCRIPTION describing the contexts in which calls to sigsetjmp () are 
valid. 


Issue 5 

The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 

Issue 6 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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NAME 

sigsuspend — wait for a signal 

Notes to Reviewers 

This section with side shading will not appear in the final copy. - Ed. 

PASC Interpretation 1003.1c #40 points out a defect in the RETURN VALUE section. "Process I 
execution" should be changed to "thread execution". This change has been applied below. 

SYNOPSIS 

#include <signal.h> 

int sigsuspend(const sigset_t *sigmask); 

DESCRIPTION 

The sigsuspend() function replaces the current signal mask of the calling thread with the set of 
signals pointed to by sigmask and then suspends the thread until delivery of a signal whose 
action is either to execute a signal-catching function or to terminate the process. This shall not 
cause any other signals that may have been pending on the process to become pending on the 
thread. 

If the action is to terminate the process then sigsuspendO shall never return. If the action is to 
execute a signal-catching function, then sigsuspendO shall return after the signal-catching 
function returns, with the signal mask restored to the set that existed prior to the sigsuspendO 
call. 

It is not possible to block signals that cannot be ignored. This is enforced by the system without 
causing an error to be indicated. 

RETURN VALUE 

Since sigsuspendO suspends thread execution indefinitely, there is no successful completion 
return value. If a return occurs, -1 shall be returned and errno set to indicate the error. 

ERRORS 

The sigsuspendO function shall fail if: 

[EINTR] A signal is caught by the calling process and control is returned from the 

signal-catching function. 

EXAMPLES 

None. 

APPLICATION USAGE 

Normally, at the beginning of a critical code section, a specified set of signals is blocked using 
the sigprocmask () function. When the process has completed the critical section and needs to 
wait for the previously blocked signal(s), it pauses by calling sigsuspendO with the mask that 
was returned by the sigprocmask () call. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

Section 2.4 on page 43, pauseO, sigaction(), sigaddsetO, sigdelset(), sigemptysetO, sigfillsetO, the 
System Interface Definitions volume of IEEE Std. 1003.1-200x, <signal.h> 
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38822 CHANGE HISTORY 

38823 First released in Issue 3. 

38824 Entry included for alignment with the POSIX.1-1988 standard. 

38825 Issue 4 

38826 The term "signal handler" is changed to "signal-catching function". 

38827 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

38828 • The type of the argument sigmask is changed from sigset_t* to const sigset t*. 

38829 Issue 5 

38830 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 

38831 Issue 6 

38832 The text in the RETURN VALUE section has been changed from "suspends process execution" 

38833 to "suspends thread execution". This reflects PASC Interpretation 1003.1c #40. 

38834 Text in the APPLICATION USAGE section has been replaced. 
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38835 NAME 

38836 sigtimedwait, sigwaitinfo — wait for queued signals (REALTIME) 

38837 SYNOPSIS 

38838 RTS #include <signal.h> 

38839 

38840 

38841 

38842 

38843 DESCRIPTION 

38844 The sigtimedwait () function behaves the same as sigwaitinfo () except that if none of the signals 

38845 specified by set are pending, sigtimedwait () waits for the time interval specified in the timespec 

38846 structure referenced by timeout. If the timespec structure pointed to by timeout is zero-valued 

38847 and if none of the signals specified by set are pending, then sigtimedwait () returns immediately 

38848 mon with an error. If timeout is the NULL pointer, the behavior is unspecified. If the Monotonic Clock I 

38849 option is supported, the CLOCK_MONOTONIC clock shall be used to measure the time interval I 

38850 specified by the timeout argument. I 

38851 The sigzvaitinfo () function selects the pending signal from the set specified by set. Should any of 

38852 multiple pending signals in the range SIGRTMIN to SIGRTMAX be selected, it shall be the 

38853 lowest numbered one. The selection order between realtime and non-realtime signals, or 

38854 between multiple pending non-realtime signals, is unspecified. If no signal in set is pending at 

38855 the time of the call, the calling thread is suspended until one or more signals in set become 

38856 pending or until it is interrupted by an unblocked, caught signal. 

38857 The sigzvaitinfo () function behaves the same as the sigzvait () function if the info argument is 

38858 NULL. If the info argument is non-NULL, the sigzvaitinfo () function behaves the same as 

38859 sigzvait (), except that the selected signal number shall be stored in the si_signo member, and the 

38860 cause of the signal shall be stored in the si_code member. If any value is queued to the selected 

38861 signal, the first such queued value shall be dequeued and, if the info argument is non-NULL, the 

38862 value shall be stored in the sijvalue member of info. The system resource used to queue the 

38863 signal shall be released and made available to queue other signals. If no value is queued, the 

38864 content of the si_value member is undefined. If no further signals are queued for the selected 

38865 signal, the pending indication for that signal shall be reset. 

38866 RETURN VALUE 

38867 Upon successful completion (that is, one of the signals specified by set is pending or is 

38868 generated) sigzvaitinfo () and sigtimedwait () shall return the selected signal number. Otherwise, 

38869 the function shall return a value of -1 and set errno to indicate the error. 

38870 ERRORS 

38871 The sigtimedwait () function shall fail if: 

38872 Notes to Reviewers 

38873 This section zvith side shading zvill not appear in the final copy. - Ed. 

38874 Dl, XSH, ERN 345 proposes that the [EAGAIN] error condition ought to be [ETIMEDOUT] as 

38875 per the same condition on pthread_cond_timedzvait (). 

38876 [EAGAIN] No signal specified by set was generated within the specified timeout period. 

38877 The sigtimedwait () and sigzvaitinfo () functions may fail if: 

38878 [EINTR] The wait was interrupted by an unblocked, caught signal. It shall be 

38879 documented in system documentation whether this error causes these 


int sigtimedwait(const sigset_t *set, siginfo_t * info, 
const struct timespec * timeout ); 
int sigwaitinfo(const sigset_t *set, siginfo_t *info); 
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38880 functions to fail. 

38881 The sigtimedzvait () function may also fail if: 

38882 [EINVAL] The timeout argument specified a tv_nsec value less than zero or greater than 

38883 or equal to 1 000 million. 

38884 An implementation only checks for this error if no signal is pending in set and it is necessary to 

38885 wait. 

38886 EXAMPLES 

38887 None. 

38888 APPLICATION USAGE 

38889 None. 

38890 RATIONALE 

38891 Existing programming practice on realtime systems uses the ability to pause waiting for a 

38892 selected set of events and handle the first event that occurs in-line instead of in a signal-handling 

38893 function. This allows applications to be written in an event-directed style similar to a state 

38894 machine. This style of programming is useful for largescale transaction processing in which the 

38895 overall throughput of an application and the ability to clearly track states are more important 

38896 than the ability to minimize the response time of individual event handling. 

38897 It is possible to construct a signal-waiting macro function out of the realtime signal function 

38898 mechanism defined in this volume of IEEE Std. 1003.1-200x. However, such a macro has to 

38899 include the definition of a generalized handler for all signals to be waited on. A significant 

38900 portion of the overhead of handler processing can be avoided if the signal-waiting function is 

38901 provided by the kernel. This volume of IEEE Std. 1003.1-200x therefore provides two signal- 

38902 waiting functions—one that waits indefinitely and one with a timeout—as part of the overall 

38903 realtime signal function specification. 

38904 The specification of a function with a timeout allows an application to be written that can be 

38905 broken out of a wait after a set period of time if no event has occurred. It was argued that setting 

38906 a timer event before the wait and recognizing the timer event in the wait would also implement 

38907 the same functionality, but at a lower performance level. Because of the performance 

38908 degradation associated with the user-level specification of a timer event and the subsequent 

38909 cancelation of that timer event after the wait completes for a valid event, and the complexity 

38910 associated with handling potential race conditions associated with the user-level method, the 

38911 separate function has been included. 

38912 Note that the semantics of the sigzvaitinfo () function are nearly identical to that of the sigwait( ) 

38913 function defined by this volume of IEEE Std. 1003.1-200x. The only difference is that sigzvaitinfo () 

38914 returns the queued signal value in the value argument. The return of the queued value is 

38915 required so that applications can differentiate between multiple events queued to the same 

38916 signal number. 

38917 The two distinct functions are being maintained because some implementations may choose to 

38918 implement the POSIX Threads Extension functions and not implement the queued signals 

38919 extensions. Note, though, that sigzvaitinfo () does not return the queued value if the value 

38920 argument is NULL, so the POSIX Threads Extension sigzvait( ) function can be implemented as a 

38921 macro on sigzvaitinfo (). 

38922 The sigtimedzvait() function was separated from the sigzvaitinfo () function to address concerns 

38923 regarding the overloading of the timeout pointer to indicate indefinite wait (no timeout), timed 

38924 wait, and immediate return, and concerns regarding consistency with other functions where the 

38925 conditional and timed waits were separate functions from the pure blocking function. The 

38926 semantics of sigtimedzvait () are specified such that sigzvaitinfo () could be implemented as a 
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38927 

38928 

38929 

38930 

38931 
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38940 
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38946 
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38948 

38949 

38950 

38951 

38952 

38953 

38954 

38955 

38956 

38957 

38958 

38959 

38960 

38961 

38962 

38963 

38964 

38965 

38966 

38967 

38968 


macro with a NULL pointer for timeout. 

The sigzvait functions provide a synchronous mechanism for threads to wait for asynchronously 
generated signals. One important question was how many threads that are suspended in a call to 
a sigzvait ( ) function for a signal should return from the call when the signal is sent. Four choices 
were considered: 

1. Return an error for multiple simultaneous calls to sigzvait functions for the same signal. 

2. One or more threads return. 

3. All waiting threads return. 

4. Exactly one thread returns. 

Prohibiting multiple calls to sigzvait () for the same signal was felt to be overly restrictive. The 
"one or more" behavior made implementation of conforming packages easy at the expense of 
forcing POSIX threads clients to protect against multiple simultaneous calls to sigzvait () in 
application code in order to achieve predictable behavior. There was concern that the "all 
waiting threads" behavior would result in "signal broadcast storms", consuming excessive CPU 
resources by replicating the signals in the general case. Furthermore, no convincing examples 
could be presented that delivery to all was either simpler or more powerful than delivery to one. 

Thus, the consensus was that exactly one thread that was suspended in a call to a sigzvait 
function for a signal should return when that signal occurs. This is not an onerous restriction as: 

• A multi-way signal wait can be built from the single-way wait. 

• Signals should only be handled by application-level code, as library routines cannot guess 
what the application wants to do with signals generated for the entire process. 

• Applications can thus arrange for a single thread to wait for any given signal and call any 
needed routines upon its arrival. 

In an application that is using signals for XSI interprocess communication, signal processing is 
typically done in one place. Alternatively, if the signal is being caught so that process cleanup 
can be done, the signal handler thread can call separate process cleanup routines for each 
portion of the application. Since the application main line started each portion of the application, 
it is at the right abstraction level to tell each portion of the application to clean up. 

Certainly, there exist programming styles where it is logical to consider waiting for a single 
signal in multiple threads. A simple sigzvait_multiple( ) routine can be constructed to achieve this 
goal. A possible implementation would be to have each sigzvait _multiple( ) caller registered as 
having expressed interest in a set of signals. The caller then waits on a thread-specific condition 
variable. A single server thread calls a sigzvait () function on the union of all registered signals. 
When the sigzvait () function returns, the appropriate state is set and condition variables are 
broadcast. New sigzvaitjnultiple() callers may cause the pending sigzvait () call to be canceled 
and reissued in order to update the set of signals being waited for. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

Section 2.8.1 on page 59, pause (), pthread_sigmask(), sigaction{), sigpending(), sigsuspend(), 
sigzvait (), the System Interface Definitions volume of IEEEStd. 1003.l-200x, <signal.h>, 
<time.h> 


System Interfaces, Issue 6 


1281 



sigtimedwait() 


System Interfaces 


38969 

38970 

38971 

38972 

38973 

38974 

38975 

38976 

38977 

38978 

38979 


CHANGE HISTORY 

First released in Issue 5. Included for alignment with the POSIX Realtime Extension and the I 
POSIX Threads Extension. I 


Issue 6 

These functions are marked as part of the _POSIX_REALTIME_SIGNALS option. 

The Open Group corrigenda item U035/3 has been applied. The SYNOPSIS of the sigzvaitinfo () 
function has been corrected so that the second argument is of type siginfo_t*. 

The [ENOSYS] error condition has been removed as stubs need not be provided if an 
implementation does not support the _POSIX_REALTIME_SIGNALS option. I 

The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that the I 
CLOCK_MONOTONIC clock, if supported, is used to measure timeout intervals. I 
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38980 NAME 

38981 sigwait — wait for queued signals 

38982 SYNOPSIS 

38983 #include <signal.h> 

38984 int sigwait (const sigset_t *set, int *sig) ; 

38985 DESCRIPTION 

38986 The sigwait () function selects a pending signal from set, atomically clears it from the system's set 

38987 of pending signals, and returns that signal number in the location referenced by sig. If prior to 

38988 the call to sigwait () there are multiple pending instances of a single signal number, it is 

38989 implementation-dependent whether upon successful return there are any remaining pending 

38990 rts signals for that signal number. If the implementation supports queued signals and there are 

38991 multiple signals queued for the signal number selected, the first such queued signal shall cause a 

38992 return from sigzvait () and the remainder shall remain queued. If no signal in set is pending at the 

38993 time of the call, the thread is suspended until one or more becomes pending. The signals defined 

38994 by set shall have been blocked at the time of the call to sigwait (); otherwise, the behavior is 

38995 undefined. The effect of sigwait () on the signal actions for the signals in set is unspecified. 

38996 If more than one thread is using sigwait () to wait for the same signal, no more than one of these 

38997 threads shall return from sigzvait () with the signal number. Which thread returns from sigwait () 

38998 if more than a single thread is waiting is unspecified. 

38999 rts Should any of the multiple pending signals in the range SIGRTMIN to SIGRTMAX be selected, it 

39000 shall be the lowest numbered one. The selection order between realtime and non-realtime 

39001 signals, or between multiple pending non-realtime signals, is unspecified. 

39002 RETURN VALUE 

39003 Upon successful completion, sigwait () shall store the signal number of the received signal at the 

39004 location referenced by sig and return zero. Otherwise, an error number shall be returned to 

39005 indicate the error. 

39006 ERRORS 

39007 The sigzvait () function may fail if: 

39008 [EINVAL] The set argument contains an invalid or unsupported signal number. 

39009 EXAMPLES 

39010 None. 

39011 APPLICATION USAGE 

39012 None. 

39013 RATIONALE 

39014 To provide a convenient way for a thread to wait for a signal, this volume of 

39015 IEEE Std. 1003.1-200x provides the sigwait () function. For most cases where a thread has to wait 

39016 for a signal, the sigzvait () function should be quite convenient, efficient, and adequate. 

39017 However, requests were made for a lower-level primitive than sigzvait () and for semaphores that 

39018 could be used by threads. After some consideration, threads were allowed to use semaphores 

39019 and sem_post () was defined to be async-signal and async-cancel-safe. 

39020 In summary, when it is necessary for code run in response to an asynchronous signal to notify a 

39021 thread, sigzvait{) should be used to handle the signal. Alternatively, if the implementation 

39022 provides semaphores, they also can be used, either following sigzvait () or from within a signal 

39023 handling routine previously registered with sigaction (). 
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39024 FUTURE DIRECTIONS 

39025 None. 

39026 SEE ALSO 

39027 Section 2.4 on page 43, Section 2.8.1 on page 59, pause{), pthread_sigmask(), sigaction(), 

39028 sigpending (), sigsuspend (), sigzvaitinfo() r the System Interface Definitions volume of 

39029 IEEE Std. 1003.1-200x, <signal.h>, <time.h> 

39030 CHANGE HISTORY 

39031 First released in Issue 5. Included for alignment with the POSIX Realtime Extension and the I 

39032 POSIX Threads Extension. I 

39033 Issue 6 

39034 The RATIONALE section is added. I 
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39035 NAME 

39036 sigwaitinfo — wait for queued signals (REALTIME) 

39037 SYNOPSIS 

39038 RTS tinclude <signal.h> 

39039 int sigwaitinfo (const sigset_t *set, siginfo_t *info); 

39040 

39041 DESCRIPTION 

39042 Refer to sigtimedwait (). 
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NAME 

sin — sine function 

SYNOPSIS 

#include <math.h> 

double sin(double x); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The sin () function shall compute the sine of its argument x, measured in radians. 

An application wishing to check for error situations should set errno to 0 before calling sin(). If 
errno is non-zero on return, or the return value is NaN, an error has occurred. 

The sin () function may lose accuracy when its argument is far from 0.0. 

RETURN VALUE 

Upon successful completion, sin () shall return the sine of x. 
xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM]. 

xsi If x is ±Inf, either 0.0 shall be returned and errno set to [EDOM], or NaN shall be returned and 

errno may be set to [EDOM]. 

If the correct result would cause underflow, 0.0 shall be returned and errno may be set to 
[ERANGE], 

ERRORS 

The sin () function may fail if: 

xsi [EDOM] The value of x is NaN, or x is ±Inf. 

[ERANGE] The result underflows, 

xsi No other errors shall occur. 

EXAMPLES 

Taking the Sine of a 45-Degree Angle 

#include <math.h> 

double radians = 45.0 * M_PI / 180; 
double result; 

result = sin (radians); 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 
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39082 SEE ALSO 

39083 asin (), is nan (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

39084 CHANGE HISTORY 

39085 First released in Issue 1. 

39086 Derived from Issue 1 of the SVID. 

39087 Issue 4 

39088 References to matherri ) are removed. 

39089 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

39090 ISO C standard and to rationalize error handling in the mathematics functions. 

39091 The return value specified for [EDOM] is marked as an extension. 

39092 Issue 5 

39093 The last two paragraphs of the DESCRIPTION were included as APPLICATION USAGE notes 

39094 in previous issues. 
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NAME 

sinh — hyperbolic sine function 

SYNOPSIS 

#include <math.h> 

double sinh(double x); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The sinh() function shall compute the hyperbolic sine of x. 

An application wishing to check for error situations should set errno to 0 before calling sinh(). If 
errno is non-zero on return, or the return value is NaN, an error has occurred. 

RETURN VALUE 

Upon successful completion, sinh() shall return the hyperbolic sine of x. 

If the result would cause an overflow, ±HUGE_VAL shall be returned and errno set to 
[ERANGE], 

If the result would cause underflow, 0.0 shall be returned and errno may be set to [ERANGE]. 
xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

ERRORS 

The sinh () function shall fail if: 

[ERANGE] The result would cause overflow. 

The sinh () function may fail if: 
xsi [EDOM] The value of x is NaN. 

[ERANGE] The result would cause underflow, 

xsi No other errors shall occur. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

asinh(), cosh (), isnan(), tanh( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

<math.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 
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39135 
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39137 
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39139 
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39141 


Issue 4 

References to matherr () are removed. 

The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 
ISO C standard and to rationalize error handling in the mathematics functions. 

The return value specified for [EDOM] is marked as an extension. 


Issue 5 

The DESCRIPTION is updated to indicate how an application should check for an error. This 
text was previously published in the APPLICATION USAGE section. 
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NAME 

sleep — suspend execution for an interval of time 

SYNOPSIS 

#include <unistd.h> 

unsigned int sleep(unsigned int seconds) ; 

DESCRIPTION 

The sleep () function shall cause the calling thread to be suspended from execution until either 
the number of realtime seconds specified by the argument seconds has elapsed or a signal is 
delivered to the calling thread and its action is to invoke a signal-catching function or to 
terminate the process. The suspension time may be longer than requested due to the scheduling 
of other activity by the system. 

If a SIGALRM signal is generated for the calling process during execution of sleep () and if the 
SIGALRM signal is being ignored or blocked from delivery, it is unspecified whether sleep () 
returns when the SIGALRM signal is scheduled. If the signal is being blocked, it is also 
unspecified whether it remains pending after sleep () returns or it is discarded. 

If a SIGALRM signal is generated for the calling process during execution of sleep (), except as a 
result of a prior call to alarm (), and if the SIGALRM signal is not being ignored or blocked from 
delivery, it is unspecified whether that signal has any effect other than causing sleep () to return. 

If a signal-catching function interrupts sleep () and examines or changes either the time a 
SIGALRM is scheduled to be generated, the action associated with the SIGALRM signal, or 
whether the SIGALRM signal is blocked from delivery, the results are unspecified. 

If a signal-catching function interrupts sleep () and calls siglongjmp () or longjmp () to restore an 
environment saved prior to the sleep () call, the action associated with the SIGALRM signal and 
the time at which a SIGALRM signal is scheduled to be generated are unspecified. It is also 
unspecified whether the SIGALRM signal is blocked, unless the process' signal mask is restored 
as part of the environment. 

xsi Interactions between sleep () and any of setit inter ( ), nalarm (), or asleep () are unspecified. 

RETURN VALUE 

If sleep () returns because the requested time has elapsed, the value returned shall be 0. If sleep () 
returns because of premature arousal due to delivery of a signal, the return value shall be the 
"unslept" amount (the requested time minus the time actually slept) in seconds. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

There are two general approaches to the implementation of the sleep () function. One is to use the 
alarm () function to schedule a SIGALRM signal and then suspend the process waiting for that 
signal. The other is to implement an independent facility. This volume of IEEE Std. 1003.1-200x 
permits either approach. 

In order to comply with the requirement that no primitive shall change a process attribute unless 
explicitly described by this volume of IEEE Std. 1003.1-200x, an implementation using SIGALRM 
must carefully take into account any SIGALRM signal scheduled by previous alarm () calls, the 
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39187 action previously established for SIGALRM, and whether SIGALRM was blocked. If a SIGALRM 

39188 has been scheduled before the sleep () would ordinarily complete, the sleep () must be shortened 

39189 to that time and a SIGALRM generated (possibly simulated by direct invocation of the signal- 

39190 catching function) before sleep () returns. If a SIGALRM has been scheduled after the sleep () 

39191 would ordinarily complete, it must be rescheduled for the same time before sleep () returns. The 

39192 action and blocking for SIGALRM must be saved and restored. 

39193 Historical implementations often implement the SIGALRM-based version using alarm () and 

39194 pause(). One such implementation is prone to infinite hangups, as described in pause( ). Another 

39195 such implementation uses the C-language setjmp() and longjmp() functions to avoid that 

39196 window. That implementation introduces a different problem: when the SIGALRM signal 

39197 interrupts a signal-catching function installed by the user to catch a different signal, the 

39198 longjmp () aborts that signal-catching function. An implementation based on sigprocmask(), 

39199 alarm (), and sigsuspend () can avoid these problems. 

39200 Despite all reasonable care, there are several very subtle, but detectable and unavoidable, 

39201 differences between the two types of implementations. These are the cases mentioned in this 

39202 volume of IEEE Std. 1003.1-200x where some other activity relating to SIGALRM takes place, 

39203 and the results are stated to be unspecified. All of these cases are sufficiently unusual as not to 

39204 be of concern to most applications. 

39205 See also the discussion of the term realtime in alarm (). 

39206 Because sleep () can be implemented using alarm (), the discussion about alarms occurring early 

39207 under alarm () applies to sleep () as well. 

39208 Application writers should note that the type of the argument seconds and the return value of 

39209 sleep () is unsigned int. That means that a Strictly Conforming POSIX System Interfaces 

39210 Application cannot pass a value greater than the minimum guaranteed value for |UINT_MAX}, 

39211 which the ISO C standard sets as 65 535, and any application passing a larger value is restricting 

39212 its portability. A different type was considered, but historical implementations, including those 

39213 with a 16-bit int type, consistently use either unsigned int or int. 

39214 Scheduling delays may cause the process to return from the sleep () function significantly after 

39215 the requested time. In such cases, the return value should be set to zero, since the formula 

39216 (requested time minus the time actually spent) yields a negative number and sleep () returns an 

39217 unsigned int. 

39218 FUTURE DIRECTIONS 

39219 None. 

39220 SEE ALSO 

39221 alarm(), getitimer( ), nanosleep(), pause(), sigaction(), sigsetjmp(), nalarm{), usleep{), the System 

39222 Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

39223 CHANGE HISTORY 

39224 First released in Issue 1. 

39225 Derived from Issue 1 of the SVID. 

39226 Issue 4 

39227 The <unistd.h> header is added to the SYNOPSIS section. 

39228 Issue 4, Version 2 

39229 The DESCRIPTION is updated to indicate possible interactions with the setitimer (), iialarm (), 

39230 and usleep( ) functions. 
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39231 issue 5 

39232 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 
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39233 NAME 

39234 socket — create an endpoint for communication 

39235 SYNOPSIS 

39236 tinclude <sys/socket. h> 


39237 


int socket(int domain, int type, int protocol); 


39238 DESCRIPTION 


39239 

39240 

39241 

39242 

39243 
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The socket () function shall create an unbound socket in a communications domain, and return a 
file descriptor that can be used in later function calls that operate on sockets. 

The socket () function takes the following arguments: 

domain Specifies the communications domain in which a socket is to be created. 

type Specifies the type of socket to be created. 

protocol Specifies a particular protocol to be used with the socket. Specifying a protocol 

of 0 causes socket () to use an unspecified default protocol appropriate for the 
requested socket type. 

The domain argument specifies the address family used in the communications domain. The 
address families supported by the system are implementation-dependent. 

Symbolic constants that can be used for the domain argument are defined in the <sys/socket.h> 
header. 

The type argument specifies the socket type, which determines the semantics of communication 
over the socket. The socket types supported by the system are implementation-dependent. 
Possible socket types include: 

SOCK_STREAM Provides sequenced, reliable, bidirectional, connection-mode byte 
streams, and may provide a transmission mechanism for out-of-band 
data. 

SOCK_DGRAM Provides datagrams, which are connectionless-mode, unreliable messages 
of fixed maximum length. 

SOCK_SEQPACKET Provides sequenced, reliable, bidirectional, connection-mode 
transmission path for records. A record can be sent using one or more 
output operations and received using one or more input operations, but a 
single operation never transfers part of more than one record. Record 
boundaries are visible to the receiver via the MSG_EOR flag. 

If the protocol argument is non-zero, it shall specify a protocol that is supported by the address 
family. The protocols supported by the system are implementation-dependent. 

The process may need to have appropriate privileges to use the socket () function or to create 
some sockets. 


39268 RETURN VALUE 

39269 Upon successful completion, socket () shall return a non-negative integer, the socket file 

39270 descriptor. Otherwise, a value of -1 shall be returned and errno set to indicate the error. 

39271 ERRORS 

39272 The socket () function shall fail if: 

39273 [EAFNOSUPPORT] 

39274 The implementation does not support the specified address family. 
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39275 [EMFILE] No more file descriptors are available for this process. 

39276 [ENFILE] No more file descriptors are available for the system. 

39277 [EPROTONOSUPPORT] 

39278 The protocol is not supported by the address family, or the protocol is not 

39279 supported by the implementation. 

39280 [EPROTOTYPE] The socket type is not supported by the protocol. 

39281 The socket () function may fail if: 

39282 [EACCES] The process does not have appropriate privileges. 

39283 [ENOBUFS] Insufficient resources were available in the system to perform the operation. 

39284 [ENOMEM] Insufficient memory was available to fulfill the request. 

39285 xsr [ENOSR] There were insufficient STREAMS resources available for the operation to 

39286 complete. 

39287 EXAMPLES 

39288 None. 

39289 APPLICATION USAGE 

39290 The documentation for specific address families specifies which protocols each address family 

39291 supports. The documentation for specific protocols specifies which socket types each protocol 

39292 supports. 

39293 The application can determine if an address family is supported by trying to create a socket with 

39294 domain set to the protocol in question. 

39295 RATIONALE 

39296 None. 

39297 FUTURE DIRECTIONS 

39298 None. 

39299 SEE ALSO 

39300 accept{), bind(), connect(), getsockname(), getsockopt(), listen(), recv{), recvfrom{), recvmsg(), 

39301 send (), sendmsg (), setsockopt(), shutdown(), socketpair(), the System Interface Definitions volume 

39302 of IEEE Std. 1003.1-200x, <netinet/in.h>, <sys/socket.h> 

39303 CHANGE HISTORY 

39304 First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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39305 NAME 

39306 socketpair — create a pair of connected sockets 

39307 SYNOPSIS 

39308 tinclude <sys/socket. h> 


39309 

39310 


int socketpair (int domain, int type, int protocol, 
int socket_vector[ 2]); 


39311 DESCRIPTION 

39312 

39313 

39314 

39315 


39316 

39317 

39318 

39319 

39320 

39321 

39322 

39323 

39324 

39325 

39326 

39327 

39328 

39329 

39330 

39331 

39332 

39333 

39334 

39335 

39336 

39337 

39338 

39339 

39340 


The socketpair () function creates an unbound pair of connected sockets in a specified domain, of a 
specified type, under the protocol optionally specified by the protocol argument. The two sockets 
are identical. The file descriptors used in referencing the created sockets are returned in 
socket yoector [0] and socket_vector[ 1]. 

The socketpair () function takes the following arguments: 

domain Specifies the communications domain in which the sockets are to be created. 

type Specifies the type of sockets to be created. 

protocol Specifies a particular protocol to be used with the sockets. Specifying a 

protocol of 0 causes socketpair () to use an unspecified default protocol 
appropriate for the requested socket type. 

socket_vector Specifies a 2-integer array to hold the file descriptors of the created socket 
pair. 

The type argument specifies the socket type, which determines the semantics of communications 
over the socket. The socket types supported by the system are implementation-dependent. 
Possible socket types include: 

SOCK_STREAM Provides sequenced, reliable, bidirectional, connection-mode byte 
streams, and may provide a transmission mechanism for out-of-band 
data. 

SOCK_DGRAM Provides datagrams, which are connectionless-mode, unreliable messages 
of fixed maximum length. 

SOCK_SEQPACKET Provides sequenced, reliable, bidirectional, connection-mode 
transmission paths for records. A record can be sent using one or more 
output operations and received using one or more input operations, but a 
single operation never transfers part of more than one record. Record 
boundaries are visible to the receiver via the MSG_EOR flag. 

If the protocol argument is non-zero, it shall specify a protocol that is supported by the address 
family. The protocols supported by the system are implementation-dependent. 

The process may need to have appropriate privileges to use the socketpair () function or to create 
some sockets. 


39341 RETURN VALUE 

39342 Upon successful completion, this function shall return 0; otherwise, -1 shall be returned and 

39343 errno set to indicate the error. 


39344 ERRORS 

39345 The socketpair () function shall fail if: 

39346 [EAFNOSUPPORT] 

39347 The implementation does not support the specified address family. 
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39348 

39349 

39350 

39351 

39352 

39353 

39354 

39355 

39356 

39357 

39358 

39359 

39360 

39361 

39362 

39363 

39364 

39365 

39366 

39367 

39368 

39369 

39370 

39371 

39372 

39373 

39374 

39375 

39376 


[EMFILE] No more file descriptors are available for this process. 

[ENFILE] No more file descriptors are available for the system. 

[EOPNOTSUPP] The specified protocol does not permit creation of socket pairs. 
[EPROTONOSUPPORT] 

The protocol is not supported by the address family, or the protocol is not 
supported by the implementation. 

[EPROTOTYPE] The socket type is not supported by the protocol. 

The socketpair () function may fail if: 

[EACCES] The process does not have appropriate privileges. 

[ENOBUFS] Insufficient resources were available in the system to perform the operation. 

[ENOMEM] Insufficient memory was available to fulfill the request. 

xsr [ENOSR] There were insufficient STREAMS resources available for the operation to 

complete. 

EXAMPLES 

None. 

APPLICATION USAGE 

The documentation for specific address families specifies which protocols each address family 
supports. The documentation for specific protocols specifies which socket types each protocol 
supports. 

The socketpair() function is used primarily with UNIX domain sockets and need not be 
supported for other domains. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

socket 0, the System Interface Definitions volume of IEEE Std. 1003.1-200x, <sys/socket.h> 
CHANGE HISTORY 

First released in Issue 6. Derived from the XNS, Issue 5.2 specification. 
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39377 NAME 

39378 sprintf, snprintf — print formatted output 

39379 SYNOPSIS 

39380 tinclude <stdio.h> 

39381 xsi int snprintf (char *s, size_t n, const char * format, /* args */ ...); 

39382 int sprintf (char *s, const char * format, 

39383 DESCRIPTION 

39384 Refer to fprin tf( ). 
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39385 NAME 

39386 sqrt — square root function 

39387 SYNOPSIS 

39388 tinclude <math.h> 

39389 double sqrt (double x) ; 

39390 DESCRIPTION 

39391 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

39392 conflict between the requirements described here and the ISO C standard is unintentional. This I 

39393 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

39394 The sqrt( ) function shall compute the square root of x, Vx. 

39395 An application wishing to check for error situations should set errno to 0 before calling sqrt( ). If 

39396 errno is non-zero on return, or the return value is NaN, an error has occurred. 

39397 RETURN VALUE 

39398 Upon successful completion, sqrt( ) shall return the square root of x. 

39399 xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

39400 xsi If x is negative, 0.0 or NaN shall be returnedand errno shall be set to [EDOM], 

39401 ERRORS 

39402 The sqrt( ) function shall fail if: 

39403 [EDOM] The value of x is negative. 

39404 The sqrt( ) function may fail if: 

39405 xsi [EDOM] The value of x is NaN. 

39406 xsi No other errors shall occur. 

39407 EXAMPLES 

39408 Taking the Square Root of 9.0 

39409 #include <math.h> 

39410 

39411 double x = 9.0; 

39412 double result; 

39413 

39414 result = sqrt (x) ; 

39415 APPLICATION USAGE 

39416 None. 

39417 RATIONALE 

39418 None. 

39419 FUTURE DIRECTIONS 

39420 None. 

39421 SEE ALSO 

39422 isnan (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h>, <stdio.h> 
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39423 CHANGE HISTORY 

39424 First released in Issue 1. 

39425 Derived from Issue 1 of the SVID. 

39426 Issue 4 

39427 References to matherr {) are removed. 

39428 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

39429 ISO C standard and to rationalize error handling in the mathematics functions. 

39430 The return value specified for [EDOM] is marked as an extension. 


39431 Issue 5 

39432 The DESCRIPTION is updated to indicate how an application should check for an error. This 

39433 text was previously published in the APPLICATION USAGE section. 
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39434 NAME 

39435 srand — pseudo-random number generator 

39436 SYNOPSIS 

39437 #include <stdlib.h> 

39438 void srand (unsigned int seed); 

39439 DESCRIPTION 

39440 Refer to rand {). 
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39441 NAME 

39442 srand48 — seed uniformly distributed double-precision pseudo-random number generator 

39443 SYNOPSIS 

39444 xsi tinclude <stdlib.h> 

39445 void srand48(long int seedval) ; 

39446 

39447 DESCRIPTION 

39448 Refer to dmnd48 (). 
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39449 NAME 

39450 srandom — seed pseudo-random number generator 

39451 SYNOPSIS 

39452 xsi tinclude <stdlib.h> 

39453 void srandom (unsigned int seed); 

39454 

39455 DESCRIPTION 

39456 Refer to initstate (). 
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39457 NAME 

39458 sscanf — convert formatted input 

39459 SYNOPSIS 

39460 #include <stdio.h> 

39461 int sscanf (const char *s, const char * format , . . . ) ; 

39462 DESCRIPTION 

39463 Refer to fsconf{ ). 
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39464 NAME 

39465 stat — get file status 

39466 SYNOPSIS 

39467 #include <sys/stat.h> 

39468 int stat (const char *path, struct stat *buf) ; 

39469 DESCRIPTION 

39470 The stat( ) function obtains information about the named file and writes it to the area pointed to 

39471 by the buf argument. The path argument points to a path name naming a file. Read, write, or 

39472 execute permission of the named file is not required, but the application shall ensure that all I 

39473 directories listed in the path name leading to the file are searchable. An implementation that I 

39474 provides additional or alternate file access control mechanisms may, under implementation- I 

39475 dependent conditions, cause stat( ) to fail. In particular, the system may deny the existence of the I 

39476 file specified by path. 

39477 If the named file is a symbolic link, the stat () function shall continue path name resolution using I 

39478 the contents of the symbolic link, and shall return information pertaining to the resulting file if I 

39479 the file exists. I 

39480 The buf argument is a pointer to a stat structure, as defined in the header <sys/stat.h>, into I 

39481 which information is placed concerning the file. 

39482 The stat () function updates any time-related fields (as described in the definition of File Times 

39483 Update in the System Interface Definitions volume of IEEE Std. 1003.1-200x), before writing into 

39484 the stat structure. 

39485 The structure members stjnode, st_ino, st_dev, st_uid, st_gid, st_atime, st_ctime, and stjntime 

39486 shall have meaningful values for all file types defined in this volume of IEEE Std. 1003.1-200x. 

39487 The value of the member st_nlink shall be set to the number of links to the file. 

39488 RETURN VALUE 

39489 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 

39490 indicate the error. 


39491 ERRORS 

39492 The stat () function shall fail if: 


39493 

39494 MAN 

39495 MAN 

39496 


[EACCES] Search permission is denied for a component of the path prefix. 

[EIO] An error occurred while reading from the file system. 

[ELOOP] A loop exists in symbolic links encountered during resolution of the path I 

argument. I 


39497 

39498 

39499 

39500 


[ENAMETOOLONG] 

The length of the path argument exceeds {PATH_MAX} or a path name 
component is longer than {NAME_MAX} while _POSIX_NO_TRUNC is in 
effect. 


39501 

39502 

39503 MAN 

39504 

39505 


[ENOENT] A component of path does not name an existing file or path is an empty string. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EOVERFLOW] The file size in bytes or the number of blocks allocated to the file or the file 
serial number cannot be represented correctly in the structure pointed to by 
buf. 


39506 


The stat () function may fail if: 
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39507 

39508 

39509 

39510 

39511 

39512 

39513 

39514 

39515 

39516 

39517 

39518 

39519 

39520 

39521 

39522 

39523 

39524 

39525 

39526 

39527 

39528 

39529 

39530 

39531 

39532 

39533 

39534 

39535 

39536 

39537 

39538 

39539 

39540 

39541 

39542 

39543 

39544 

39545 

39546 

39547 

39548 

39549 

39550 


[ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during I 

resolution of the path argument. I 

man [ENAMETOOLONG] 

As a result of encountering a symbolic link in resolution of the path argument, I 
the length of the substituted path name string exceeded {PATH_MAX}. I 

man [EOVERFLOW] A value to be stored would overflow one of the members of the stat structure. 

EXAMPLES 

Obtaining File Status Information 

The following example shows how to obtain file status information for a file named 
/home/cnd/modl. The structure variable buffer is defined for the stat structure. 

#include <sys/types.h> 

#include <sys/stat.h> 

#include <fcntl.h> 

struct stat buffer; 
int status; 

status = stat("/home/cnd/modl", Sbuffer); 


Getting Directory Information 

The following example fragment gets status information for each entry in a directory. The call to 
the stat() function stores file information in the stat structure pointed to by statbuf. The lines 
that follow the stat () call format the fields in the stat structure for presentation to the user of the 
program. 

#include <sys/types.h> 

#include <sys/stat.h> 

#include <dirent.h> 

#include <pwd.h> 

#include <grp.h> 

#include <time.h> 

#include <locale.h> 

#include <langinfo.h> 


struct dirent 
struct stat 
struct passwd 
struct group 
struct tm 
char 


*dp; 

statbuf; 

*pwd; 

*grp; 

*tm; 

datestring[256] ; 


/* Loop through directory entries */ 
while ((dp = readdir (dir)) != NULL) { 

/* Get entry's information. */ 
if (stat (dp->d_name, Sstatbuf) == -1) 
continue; 

/* Print out type, permissions, and number of links. */ 
printf ("%10.10s", sperm (statbuf.st_mode)); 
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39551 printf ("%4d", statbuf. st_nlink) ; 

39552 /* Print out owners name if it is found using getpwuidO . */ 

39553 if ( (pwd = getpwuid (statbuf. st_uid) ) != NULL) 

39554 printf (" %-8.8s", pwd->pw_name) ; 

39555 else 

39556 printf (" %-8d", statbuf. st_uid) ; 

39557 /* Print out group name if it's found using getgrgidO . */ 

39558 if ((grp = getgrgid (statbuf. st_gid) ) != NULL) 

39559 printf (" %-8.8s", grp->gr_name) ; 

39560 else 

39561 printf (" %-8d", statbuf. st_gid) ; 

39562 /* Print size of file. */ 

39563 printf ("%91d", statbuf . st_size) ; 

39564 tm = localtime (Sstatbuf. st_mtime) ; 

39565 /* Get localized date string. */ 

39566 strftime (datestring, sizeof (datestring) , nl_langinfo (D_T_FMT) , tm) ; 

39567 printf (" %s %s\n", datestring, dp->d_name); 

39568 } 

39569 APPLICATION USAGE 

39570 None. 

39571 RATIONALE 

39572 The intent of the paragraph describing "additional or alternate file access control mechanisms" 

39573 is to allow a secure implementation where a process with a label that does not dominate the 

39574 file's label cannot perform a stat( ) function. This is not related to read permission; a process with 

39575 a label that dominates the file's label does not need read permission. An implementation that 

39576 supports write-up operations could fail fstat() function calls even though it has a valid file 

39577 descriptor open for writing. 

39578 FUTURE DIRECTIONS 

39579 None. 

39580 SEE ALSO 

39581 lstat(), readlink(), symlink (), the System Interface Definitions volume of I 

39582 IEEE Std. 1003.1-200x, <sys/stat.h>, <sys/types.h> 

39583 CHANGE HISTORY 

39584 First released in Issue 1. 

39585 Derived from Issue 1 of the SVID. 

39586 Issue 4 

39587 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

39588 XSI-conformant systems. 

39589 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

39590 • The type of argument path is changed from char* to const char*. 

39591 • In the DESCRIPTION is changed as follows: 

39592 — Statements indicating the purpose of this function and a paragraph defining the contents 

39593 of stat structure members are added. 
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39594 

39595 

39596 

39597 

39598 

39599 

39600 

39601 

39602 

39603 

39604 

39605 

39606 

39607 

39608 

39609 

39610 

39611 

39612 

39613 

39614 

39615 

39616 

39617 

39618 

39619 

39620 

39621 

39622 

39623 

39624 

39625 

39626 

39627 

39628 

39629 

39630 


— The words "extended security controls" are replaced by "additional or alternate file 
access control mechanisms". 

The following change is incorporated for alignment with the FIPS requirements: 

• In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 
name component is larger than |NAME_MAX[ is now defined as mandatory and marked as 
an extension. 

Issue 4, Version 2 

The ERRORS section is updated for X/OPEN UNIX conformance as follows: 

• In the mandatory section, [EIO] is added to indicate that a physical I/O error has occurred, 
and [ELOOP] to indicate that too many symbolic links were encountered during path name 
resolution. 

• In the optional section, a second [ENAMETOOLONG] condition is defined that may report 
excessive length of an intermediate result of path name resolution of a symbolic link. 

• In the optional section, [EOVERFLOW] is added to indicate that a value to be stored in a 
member of the stat structure would cause overflow. 


Issue 5 

Large File Summit extensions are added. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 
This is since behavior may vary from one file system to another. 

The following new requirements on POSIX implementations derive from alignment with the 

Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• The [EIO] mandatory error condition is added. 

• The [ELOOP] mandatory error condition is added. 

• The [EOVERFLOW] mandatory error condition is added. This change is to support large 
files. 

• The [ENAMETOOLONG] and the second [EOVERFLOW] optional error conditions are 
added. 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• Details are added regarding the treatment of symbolic links. 

• The [ELOOP] optional error condition is added. 

The DESCRIPTION is updated to avoid use of the term "must" for application requirements. 
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39631 NAME 

39632 statvfs — get file system information 

39633 SYNOPSIS 

39634 xsi #include <sys/statvf s . h> 

39635 int statvfs (const char *path, struct statvfs *buf) ; 

39636 

39637 DESCRIPTION 

39638 Refer to fstatvfs (). 
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39639 NAME 

39640 stderr, stdin, stdout — standard I/O streams 

39641 SYNOPSIS 

39642 #include <stdio.h> 

39643 extern FILE * stderr, *stdin, * stdout; 

39644 DESCRIPTION 

39645 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

39646 conflict between the requirements described here and the ISO C standard is unintentional. This I 

39647 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

39648 A file with associated buffering is called a stream and is declared to be a pointer to a defined type 

39649 FILE. The /open () function creates certain descriptive data for a stream and returns a pointer to 

39650 designate the stream in all further transactions. Normally, there are three open streams with 

39651 constant pointers declared in the <stdio.h> header and associated with the standard open files. 

39652 At program start-up, three streams are predefined and need not be opened explicitly: standard I 

39653 input (for reading conventional input), standard output (for writing conventional output), and 

39654 standard error (for writing diagnostic output). When opened, the standard error stream is not 

39655 fully buffered; the standard input and standard output streams are fully buffered if and only if 

39656 the stream can be determined not to refer to an interactive device. 

39657 cx The following symbolic values in <unistd.h> define the file descriptors that shall be associated 

39658 with the C-language stdin, stdout, and stderr when the application is started: 

39659 STDIN_FILENO Standard input value, stdin . Its value is 0. 

39660 STDOUT_FILENO Standard output value, stdout. its value is 1. 

39661 STDERR_FILENO Standard error value, stderr. Its value is 2. 

39662 

39663 RETURN VALUE 

39664 None. 

39665 ERRORS 

39666 No errors are defined. 

39667 EXAMPLES 

39668 None. 

39669 APPLICATION USAGE 

39670 None. 

39671 RATIONALE 

39672 None. 

39673 FUTURE DIRECTIONS 

39674 None. 

39675 SEE ALSO 

39676 / close(), feof(), /error (), fileno(), /open (), /read (), fseek(), getc(), gets(), popen(), printf(), putc{), 

39677 puts (), read(), scanf(), setbuf{), setvbuf(), tmpfile(), ungetc(), vprintf(), the System Interface 

39678 Definitions volume of IEEE Std. 1003.1-200x, <stdio.h>, <unistd.h> 


System Interfaces, Issue 6 


1309 



stdin 


System Interfaces 


39679 CHANGE HISTORY 

39680 First released in Issue 1. 

39681 Issue 6 

39682 Extensions beyond the ISO C standard are now marked. 
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39683 

39684 

39685 

39686 

39687 

39688 

39689 

39690 

39691 

39692 

39693 

39694 

39695 

39696 

39697 

39698 

39699 

39700 

39701 

39702 

39703 

39704 

39705 

39706 

39707 

39708 

39709 

39710 

39711 

39712 

39713 

39714 

39715 

39716 

39717 

39718 

39719 

39720 

39721 

39722 

39723 


NAME 

strcasecmp, strncasecmp — case-insensitive string comparisons 


Notes to Reviewers 

This section with side shading will not appear in the final copy. - Ed. 


This function or these functions are recommended to become mandatory parts of POSIX.l in the 
next draft. 


SYNOPSIS 

xsi tinclude <strings.h> 

int strcasecmp(const char *sl, const char *s2); 

int strncasecmp(const char *sl, const char *s2, size_t n ); 


DESCRIPTION 

The strcasecmpO function compares, while ignoring differences in case, the string pointed to by 
si to the string pointed to by s2. The strncasecmp0 function compares, while ignoring 
differences in case, not more than n bytes from the string pointed to by si to the string pointed to 
by s2. 

In the POSIX locale, strcasecmpO and strncasecmp0 do upper to lower conversions, then a byte 
comparison. The results are unspecified in other locales. 

RETURN VALUE 

Upon completion, strcasecmp () shall return an integer greater than, equal to, or less than 0, if the 
string pointed to by si is, ignoring case, greater than, equal to, or less than the string pointed to 
by s2, respectively. 

Upon successful completion, strncasecmp () shall return an integer greater than, equal to, or less 
than 0, if the possibly null-terminated array pointed to by si is, ignoring case, greater than, equal 
to, or less than the possibly null-terminated array pointed to by s2, respectively. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

The System Interface Definitions volume of IEEE Std. 1003.1-200x, <strings.h> 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 
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39724 NAME 

39725 strcat — concatenate two strings 

39726 SYNOPSIS 

39727 #include <string.h> 

39728 char *strcat (char *sl, const char *s2); 

39729 DESCRIPTION 

39730 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

39731 conflict between the requirements described here and the ISO C standard is unintentional. This I 

39732 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

39733 The strcat () function shall append a copy of the string pointed to by s2 (including the 

39734 terminating null byte) to the end of the string pointed to by si . The initial byte of s2 overwrites 

39735 the null byte at the end of si. If copying takes place between objects that overlap, the behavior is 

39736 undefined. 

39737 RETURN VALUE 

39738 The strcat () function shall return si ; no return value is reserved to indicate an error. 

39739 ERRORS 

39740 No errors are defined. 

39741 EXAMPLES 

39742 None. 

39743 APPLICATION USAGE 

39744 This issue is aligned with the ISO C standard; this does not affect compatibility with XPG3 

39745 applications. Reliable error detection by this function was never guaranteed. 

39746 RATIONALE 

39747 None. 

39748 FUTURE DIRECTIONS 

39749 None. 

39750 SEE ALSO 

39751 strncat( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

39752 CHANGE HISTORY 

39753 First released in Issue 1. 

39754 Derived from Issue 1 of the SVID. 

39755 Issue 4 

39756 The DESCRIPTION is changed to make it clear that the function manipulates bytes rather than 

39757 (possibly multi-byte) characters. 

39758 The following change is incorporated for alignment with the ISO C standard: 

39759 • The type of argument s2 is changed from char* to const char*. 
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39760 

39761 

39762 

39763 

39764 

39765 

39766 

39767 

39768 

39769 

39770 

39771 

39772 

39773 

39774 

39775 

39776 

39777 

39778 

39779 

39780 

39781 

39782 

39783 

39784 

39785 

39786 

39787 

39788 

39789 

39790 

39791 

39792 

39793 

39794 

39795 

39796 


NAME 

strchr — string scanning operation 

SYNOPSIS 

#include <string.h> 

char *strchr(const char *s, int c) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

cx The strchr () function shall locate the first occurrence of c (converted to an unsigned char) in the 

string pointed to by s. The terminating null byte is considered to be part of the string. 

RETURN VALUE 

Upon completion, strchr () shall return a pointer to the byte, or a null pointer if the byte was not 
found. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

strrchr (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The DESCRIPTION and RETURN VALUE sections are changed to make it clear that the function 
manipulates bytes rather than (possibly multi-byte) characters. 

The APPLICATION USAGE section is removed. 

The following change is incorporated for alignment with the ISO C standard: 

• The type of argument s is changed from char’'' to const char’''. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 
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39797 NAME 

39798 strcmp — compare two strings 

39799 SYNOPSIS 

39800 #include <string.h> 

39801 int strcmp (const char *sl, const char *s2); 

39802 DESCRIPTION 

39803 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

39804 conflict between the requirements described here and the ISO C standard is unintentional. This I 

39805 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

39806 The strcmp () function shall compare the string pointed to by si to the string pointed to by s2. 

39807 The sign of a non-zero return value shall be determined by the sign of the difference between the 

39808 values of the first pair of bytes (both interpreted as type unsigned char) that differ in the strings 

39809 being compared. 

39810 RETURN VALUE 

39811 Upon completion, strcmp () shall return an integer greater than, equal to, or less than 0, if the 

39812 string pointed to by si is greater than, equal to, or less than the string pointed to by s2, 

39813 respectively. 

39814 ERRORS 

39815 No errors are defined. 

39816 EXAMPLES 

39817 Checking a Password Entry 

39818 The following example compares the information read from standard input to the value of the 

39819 name of the user entry. If the strcmp () function returns 0 (indicating a match), a further check 

39820 will be made to see if the user entered the proper old password. The crypt( ) function is used to 

39821 encrypt the old password entered by the user, using the value of the encrypted password in the 

39822 passwd structure as the salt. If this value matches the value of the encrypted passwd in the 

39823 structure, the entered password oldpassivd is the correct user's password. Finally, the program 

39824 encrypts the new password so that it can store the imformation in the passwd structure. 

39825 #include <string.h> 

39826 #include <unistd.h> 

39827 #include <stdio.h> 

39828 

39829 int valid_change; 

39830 struct passwd *p; 

39831 char user[100]; 

39832 char oldpasswd [ 100 ] ; 

39833 char newpasswd [ 100 ] ; 

39834 char savepasswd [ 100 ] ; 

39835 

39836 if (strcmp (p->pw_name, user) == 0) { 

39837 if (strcmp (p->pw_passwd, crypt (oldpasswd, p->pw_passwd) ) == 0) { 

39838 strcpy (savepasswd, crypt (newpasswd, user) ) ; 

39839 p->pw_passwd = savepasswd; 

39840 valid_change = 1; 

39841 } 

39842 else { 
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39843 fprintf (stderr, "Old password is not valid\n"); 

39844 } 

39845 } 

39846 

39847 APPLICATION USAGE 

39848 None. 

39849 RATIONALE 

39850 None. 

39851 FUTURE DIRECTIONS 

39852 None. 

39853 SEE ALSO 

39854 strncmp( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

39855 CHANGE HISTORY 

39856 First released in Issue 1. 

39857 Derived from Issue 1 of the SVID. 

39858 Issue 4 

39859 The DESCRIPTION is changed to make it clear that strcmp() compares bytes rather than 

39860 (possibly multi-byte) characters. 

39861 The following change is incorporated for alignment with the ISO C standard: 

39862 • The type of arguments si and s2 is changed from char 51 ' to const char*. 

39863 Issue 6 

39864 Extensions beyond the ISO C standard are now marked. 
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39865 NAME 

39866 strcoll — string comparison using collating information 

39867 SYNOPSIS 

39868 #include <string.h> 

39869 int strcoll (const char *sl, const char *s2); 

39870 DESCRIPTION 

39871 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

39872 conflict between the requirements described here and the ISO C standard is unintentional. This I 

39873 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

39874 The strcoll () function shall compare the string pointed to by si to the string pointed to by s2, 

39875 both interpreted as appropriate to the LCJZOLLATE category of the current locale. 

39876 cx The strcoll () function shall not change the setting of errno if successful. 

39877 Because no return value is reserved to indicate an error, an application wishing to check for error 

39878 situations should set errno to 0, then call strcoll (), then check errno. 

39879 RETURN VALUE 

39880 Upon successful completion, strcoll () shall return an integer greater than, equal to, or less than 0, 

39881 according to whether the string pointed to by si is greater than, equal to, or less than the string 

39882 cx pointed to by s2 when both are interpreted as appropriate to the current locale. On error, 

39883 strcoll () may set errno, but no return value is reserved to indicate an error. 

39884 ERRORS 

39885 The strcoll () function may fail if: 

39886 cx [EINVAL] The si or s2 arguments contain characters outside the domain of the collating 

39887 sequence. 

39888 EXAMPLES 

39889 Comparing Nodes 

39890 The following example uses an application-defined function, node_compare(), to compare two 

39891 nodes based on an alphabetical ordering of the string field. 

39892 #include <string.h> 

39893 

39894 struct node { /* These are stored in the table. */ 

39895 char *string; 

39896 int length; 

39897 } ; 

39898 

39899 int node_compare (const void *nodel, const void *node2) 

39900 { 

39901 return strcoll (( (const struct node *)nodel)->string, 

39902 ((const struct node * ) node2 ) ->string) ; 

39903 } 

39904 

39905 APPLICATION USAGE 

39906 The strxfrm{) and strcmpi ) functions should be used for sorting large lists. 
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39907 

39908 

39909 

39910 

39911 

39912 

39913 

39914 

39915 

39916 

39917 

39918 

39919 

39920 

39921 

39922 

39923 

39924 

39925 

39926 

39927 

39928 

39929 


RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

strcmpi ), strxfrm (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

CHANGE HISTORY 

First released in Issue 3. 

Issue 4 

A paragraph describing how the sign of the return value should be determined is removed from 
the DESCRIPTION. 

The [EINVAL] error is marked as an extension. 

The following changes are incorporated for alignment with the ISO C standard: 

• The function is no longer marked as an extension. 

• The type of arguments si and s2 are changed from char’'' to const char*. 

Issue 5 

The DESCRIPTION is updated to indicate that errno does not be changed if the function is 
successful. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The [EINVAL] optional error condition is added. 
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39930 NAME 

39931 strcpy — copy a string 

39932 SYNOPSIS 

39933 #include <string.h> 

39934 char *strcpy(char *sl, const char *s2); 

39935 DESCRIPTION 

39936 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

39937 conflict between the requirements described here and the ISO C standard is unintentional. This I 

39938 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

39939 The strcpy () function shall copy the string pointed to by s2 (including the terminating null byte) 

39940 into the array pointed to by si . If copying takes place between objects that overlap, the behavior 

39941 is undefined. 

39942 RETURN VALUE 

39943 The strcpy () function shall return si ; no return value is reserved to indicate an error. 

39944 ERRORS 

39945 No errors are defined. 

39946 EXAMPLES 

39947 Initializing a String 

39948 The following example copies the string "-" into the permstring variable. 

39949 #include <string.h> 

39950 

39951 static char permstring [ 11 ] ; 

39952 

39953 strcpy (permstring, "-"); 

39954 

39955 Storing a Key and Data 

39956 The following example allocates space for a key using malloc () then uses strcpy () to place the 

39957 key there. Then it allocates space for data using malloc (), and uses strcpy () to place data there. 

39958 (The user-defined function dbfree( ) frees memory previously allocated to an array of type struct 

39959 element*.) 

39960 #include <string.h> 

39961 #include <stdlib.h> 

39962 #include <stdio.h> 

39963 

39964 /* Structure used to read data and store it. */ 

39965 struct element { 

39966 char *key; 

39967 char *data; 

39968 } ; 

39969 struct element *tbl, *curtbl; 

39970 char *key, *data; 

39971 int count; 

39972 

39973 void dbfree (struct element *, int); 
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39974 

39975 if ( (curtbl->key = malloc (strlen (key) +1)) == NULL) { 

39976 perror ("malloc"); dbfree (tbl, count); return NULL; 

39977 } 

39978 strcpy (curtbl->key, key) ; 

39979 if ( (curtbl->data = malloc (strlen (data) +1)) == NULL) { 

39980 perror ("malloc"); free (curtbl->key); dbfree (tbl, count); return NULL; 

39981 } 

39982 strcpy (curtbl->data, data) ; 

39983 

39984 APPLICATION USAGE 

39985 Character movement is performed differently in different implementations. Thus, overlapping 

39986 moves may yield surprises. 

39987 This issue is aligned with the ISO C standard; this does not affect compatibility with XPG3 

39988 applications. Reliable error detection by this function was never guaranteed. 

39989 RATIONALE 

39990 None. 

39991 FUTURE DIRECTIONS 

39992 None. 

39993 SEE ALSO 

39994 strncpy( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

39995 CHANGE HISTORY 

39996 First released in Issue 1. 

39997 Derived from Issue 1 of the SVID. 

39998 Issue 4 

39999 The DESCRIPTION is changed to make it clear that the function manipulates bytes rather than 

40000 (possibly multi-byte) characters. 

40001 The following change is incorporated for alignment with the ISO C standard: 

40002 • The type of argument s2 is changed from char* to const char*. 
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40003 

40004 

40005 

40006 

40007 

40008 

40009 

40010 

40011 

40012 

40013 

40014 

40015 

40016 

40017 

40018 

40019 

40020 

40021 

40022 

40023 

40024 

40025 

40026 

40027 

40028 

40029 

40030 

40031 

40032 

40033 

40034 

40035 

40036 

40037 

40038 

40039 

40040 

40041 

40042 


NAME 

strcspn — get length of a complementary substring 

SYNOPSIS 

#include <string.h> 

size_t strcspn(const char *sl, const char *s2); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The strcspn () function shall compute the length of the maximum initial segment of the string 
pointed to by si which consists entirely of bytes not from the string pointed to by s2. 

RETURN VALUE 

The strcspn () function shall return the length of the computed segment of the string pointed to 
by si ; no return value is reserved to indicate an error. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

strspn(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The DESCRIPTION is changed to make it clear that the function manipulates bytes rather than 
(possibly multi-byte) characters. 

The following change is incorporated for alignment with the ISO C standard: 

• The type of arguments si and s2 is changed from char* to const char*. 

Issue 5 

The RETURN VALUE section is updated to indicated that strcspn () returns the length of si , and 
not si itself as was previously stated. 

Issue 6 

The Open Group corrigenda item U030/1 has been applied. The text of the RETURN VALUE 
section is updated to indicate that the computed segment length is returned, not the si length. 
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40043 NAME 

40044 strdup — duplicate a string 

40045 SYNOPSIS 

40046 xsi #include <string.h> 

40047 char *strdup(const char *sl); 

40048 

40049 DESCRIPTION 

40050 The strdup () function shall return a pointer to a new string, which is a duplicate of the string 

40051 pointed to by si. The returned pointer can be passed to free( ). A null pointer is returned if the 

40052 new string cannot be created. 

40053 RETURN VALUE 

40054 The strdup () function shall return a pointer to a new string on success. Otherwise, it shall return 

40055 a null pointer and set errno to indicate the error. 

40056 ERRORS 

40057 The strdup () function may fail if: 

40058 [ENOMEM] Storage space available is insufficient. 

40059 EXAMPLES 

40060 None. 

40061 APPLICATION USAGE 

40062 None. 

40063 RATIONALE 

40064 None. 

40065 FUTURE DIRECTIONS 

40066 None. 

40067 SEE ALSO 

40068 free( ), malloc{ ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

40069 CHANGE HISTORY 

40070 First released in Issue 4, Version 2. 

40071 Issue 5 

40072 Moved from X/OPEN UNIX extension to BASE. 
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40073 NAME 

40074 strerror — get error message string 

40075 SYNOPSIS 

40076 tinclude <string.h> 

40077 char *strerror (int errnum) ; 

40078 DESCRIPTION 

40079 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

40080 conflict between the requirements described here and the ISO C standard is unintentional. This 

40081 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 

40082 cx The strerror( ) function maps the error number in errnum to a locale-dependent error message 

40083 string and returns a pointer to it. The application shall not modify the string pointed to by 

40084 cx strerror( ), which may be overwritten by a subsequent call to strerror( ) or perror (). 

40085 xsi The contents of the error message strings returned by strerror( ) should be determined by the 

40086 setting of the LC_MESSAGES category in the current locale. 

40087 The implementation shall behave as if no function defined in this volume of 

40088 IEEE Std. 1003.1-200x calls strerror (). 

40089 cx The strerror( ) function shall not change the setting of errno if successful. 

40090 Because no return value is reserved to indicate an error, an application wishing to check for error 

40091 situations should set errno to 0, then call strerror (), then check errno. 

40092 The strerror( ) function need not be reentrant. A function that is not required to be reentrant is 

40093 not required to be thread-safe. 

40094 RETURN VALUE 

40095 cx Upon successful completion, strerror( ) shall return a pointer to the generated message string. 

40096 On error errno may be set, but no return value is reserved to indicate an error. 

40097 ERRORS 

40098 The strerror( ) function may fail if: 

40099 cx [EINVAL] The value of errnum is not a valid error number. 

40100 EXAMPLES 

40101 None. 

40102 APPLICATION USAGE 

40103 None. 

40104 RATIONALE 

40105 None. 

40106 FUTURE DIRECTIONS 

40107 None. 

40108 SEE ALSO 

40109 perror( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

40110 CHANGE HISTORY 

40111 First released in Issue 3. 
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40112 Issue 4 

40113 

40114 

40115 

40116 

40117 

40118 

40119 

40120 

40121 

40122 

40123 Issue 5 

40124 

40125 

40126 Issue 6 

40127 

40128 

40129 

40130 

40131 

40132 


The DESCRIPTION is changed as follows: 

• The term "language-dependent” is replaced by "locale-dependent". 

• A statement about the use of the LC_MESSAGES category for determining the language of 
error messages is added and marked as an extension. 

The fact that s trerror() can return a null pointer on failure and set errno is marked as an 
extension. 

The [EINVAL] error is marked as an extension. 

The FUTURE DIRECTIONS section is removed. 

The following change is incorporated for alignment with the ISO C standard: 

• The function is no longer marked as an extension. 

The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 

A note indicating that this function need not be reentrant is added to the DESCRIPTION. 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the RETURN VALUE section, the fact that errno may be set is added. 

• The [EINVAL] optional error condition is added. 

The DESCRIPTION is updated to avoid use of the term "must" for application requirements. 
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40133 

40134 

40135 

40136 

40137 

40138 

40139 

40140 

40141 

40142 

40143 

40144 

40145 

40146 

40147 

40148 

40149 

40150 

40151 

40152 

40153 

40154 

40155 

40156 

40157 

40158 

40159 

40160 

40161 

40162 

40163 

40164 

40165 

40166 

40167 

40168 

40169 

40170 


NAME 

strfmon — convert monetary value to a string 

SYNOPSIS 

xsi tinclude <monetary.h> 

ssize_t strfmon(char *s, size_t maxsize, const char * format, ...); 


DESCRIPTION 

The strfmon () function shall place characters into the array pointed to by s as controlled by the 
string pointed to by format . No more than maxsize bytes are placed into the array. 

The format is a character string that contains two types of objects: plain characters, which are 
simply copied to the output stream, and conversion specifications, each of which results in the 
fetching of zero or more arguments which are converted and formatted. The results are 
undefined if there are insufficient arguments for the format. If the format is exhausted while 
arguments remain, the excess arguments are simply ignored. 

The application shall ensure that a conversion specification consists of the following sequence: I 

• A ' %' character 

• Optional flags 

• Optional field width 

• Optional left precision 

• Optional right precision 

• A required conversion character that determines the conversion to be performed 

Flags 

One or more of the following optional flags can be specified to control the conversion: 

=/ An ' =' followed by a single character/which is used as the numeric fill character. The I 
application shall ensure that the fill character is representable in a single byte in order I 
to work with precision and width counts. The default numeric fill character is the I 
<space> character. This flag does not affect field width filling which always uses the 
<space> character. This flag is ignored unless a left precision (see below) is specified. 

A Do not format the currency amount with grouping characters. The default is to insert 

the grouping characters if defined for the current locale. 

+ or ( Specify the style of representing positive and negative currency amounts. Only one of 
' +' or ' (' maybe specified. If ' +' is specified, the locale's equivalent of ' + ' and 
are used (for example, in the U.S., the empty string if positive and if negative). If 
' (' is specified, negative amounts are enclosed within parentheses. If neither flag is 
specified, the ' +' style is used. 

! Suppress the currency symbol from the output conversion. 

- Specify the alignment. If this flag is present all fields are left-justified (padded to the 

right) rather than right-justified. 
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40171 

40172 

40173 

40174 

40175 

40176 

40177 

40178 

40179 

40180 

40181 

40182 

40183 

40184 

40185 

40186 

40187 

40188 

40189 

40190 

40191 

40192 

40193 

40194 

40195 

40196 

40197 

40198 

40199 

40200 

40201 

40202 

40203 

40204 

40205 

40206 

40207 

40208 

40209 

40210 


Field Width 

zv A decimal digit string iv specifying a minimum field width in bytes in which the result 

of the conversion is right-justified (or left-justified if the flag is specified). The 
default is 0. 

Left Precision 

#n A ' #' followed by a decimal digit string n specifying a maximum number of digits 
expected to be formatted to the left of the radix character. This option can be used to 
keep the formatted output from multiple calls to the strfmon () function aligned in the 
same columns. It can also be used to fill unused positions with a special character as in 
"$***123.45". This option causes an amount to be formatted as if it has the number 
of digits specified by n. If more than n digit positions are required, this conversion 
specification is ignored. Digit positions in excess of those actually required are filled 
with the numeric fill character (see the =/flag above). 

If grouping has not been suppressed with the ' "' flag, and it is defined for the current 
locale, grouping separators are inserted before the fill characters (if any) are added. 
Grouping separators are not applied to fill characters even if the fill character is a digit. 

To ensure alignment, any characters appearing before or after the number in the 
formatted output such as currency or sign symbols are padded as necessary with 
<space> characters to make their positive and negative formats an equal length. 

Right Precision 

. p A period followed by a decimal digit string p specifying the number of digits after the 

radix character. If the value of the right precision p is 0, no radix character appears. If a 
right precision is not included, a default specified by the current locale is used. The 
amount being formatted is rounded to the specified number of digits prior to 
formatting. 

Conversion Characters 

The conversion characters and their meanings are: 

i The double argument is formatted according to the locale's international currency 

format (for example, in the U.S.: USD 1,234.56). 

n The double argument is formatted according to the locale's national currency format 

(for example, in the U.S.: $1,234.56). 

% Convert to a ' %'; no argument is converted. The entire conversion specification shall I 

be "%%". I 

Locale Information 

The LC_MONETARY category of the program's locale affects the behavior of this function 
including the monetary radix character (which may be different from the numeric radix 
character affected by the LC_NUMERIC category), the grouping separator, the currency 
symbols, and formats. The international currency symbol should be conformant with the 
ISO 4217:1995 standard. 

If the value of maxsize is greater than {SSIZE_MAX}, the result is implementation-dependent. 
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40211 RETURN VALUE 

40212 If the total number of resulting bytes including the terminating null byte is not more than 

40213 maxsize, strfmon() shall return the number of bytes placed into the array pointed to by s, not 

40214 including the terminating null byte. Otherwise, -1 shall be returned, the contents of the array are 

40215 indeterminate, and errno shall be set to indicate the error. 

40216 ERRORS 

40217 The strfmon () function shall fail if: 

40218 [E2BIG] Conversion stopped due to lack of space in the buffer. 

40219 EXAMPLES 

40220 Given a locale for the U.S. and the values 123.45, -123.45, and 3456.781: 


40221 

40222 

Conversion 

Specification 

Output 

Comments 

40223 

%n 

$123.45 

Default formatting. 

40224 


-$123.45 


40225 


$3,456.78 


40226 

%lln 

$123.45 

Right align within an 11 character field. 

40227 


-$123.45 


40228 


$3,456.78 


40229 

%#5 n 

$ 123.45 

Aligned columns for values up to 99,999. 

40230 


-$ 123.45 


40231 


$ 3,456.78 


40232 

%=*#5 n 

$***123.45 

Specify a fill character. 

40233 


-$***123.45 


40234 


$*3,456.78 


40235 

%=0#5 n 

$000123.45 

Fill characters do not use grouping 

40236 


-$000123.45 

even if the fill character is a digit. 

40237 


$03,456.78 


40238 

%~#5 n 

$ 123.45 

Disable the grouping separator. 

40239 


-$ 123.45 


40240 


$ 3456.78 


40241 

%" #5. On 

$ 123 

Round off to whole units. 

40242 


-$ 123 


40243 


$ 3457 


40244 

%" #5. 4 n 

$ 123.4500 

Increase the precision. 

40245 


-$ 123.4500 


40246 


$ 3456.7810 


40247 

% (#517 

123.45 

Use an alternative pos/neg style. 

40248 


($ 123.45) 


40249 


$ 3,456.78 


40250 

% (#577 

123.45 

Disable the currency symbol. 

40251 


( 123.45) 


40252 


3,456.78 



40253 APPLICATION USAGE 

40254 None. 
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40255 RATIONALE 

40256 None. 

40257 FUTURE DIRECTIONS 

40258 Lowercase conversion characters are reserved for future standards use and uppercase for 

40259 implementation-dependent use. 

40260 SEE ALSO 

40261 localeconv(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <monetary.h> 

40262 CHANGE HISTORY 

40263 First released in Issue 4. 

40264 Issue 5 

40265 Moved from ENHANCED I18N to BASE. 

40266 The [ENOSYS] error is removed. 

40267 A sentence is added to the DESCRIPTION warning about values of maxsize that are greater than 

40268 {SSIZE_MAX}. 

40269 Issue 6 

40270 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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40271 NAME 

40272 strftime — convert date and time to a string 

40273 SYNOPSIS 

40274 #include <time.h> 

40275 size_t strftime (char *s, size_t maxsize, const char * format, 

40276 const struct tm *t imptr) ; 

40277 DESCRIPTION 

40278 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

40279 conflict between the requirements described here and the ISO C standard is unintentional. This I 

40280 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

40281 The strftimei ) function shall place bytes into the array pointed to by s as controlled by the string 

40282 pointed to by format. The format string consists of zero or more conversion specifications and 

40283 ordinary characters. A conversion specification consists of a ' %' character and a terminating 

40284 conversion character that determines the conversion specification's behavior. All ordinary 

40285 characters (including the terminating null byte) are copied unchanged into the array. If copying 

40286 takes place between objects that overlap, the behavior is undefined. No more than maxsize bytes 

40287 are placed into the array. Each conversion specification is replaced by appropriate characters as 

40288 described in the following list. The appropriate characters are determined by the program's 

40289 locale and by the values contained in the structure pointed to by timptr. 

40290 cx Local timezone information is used as though strftimei ) called tzset( ). 

40291 %a Replaced by the locale's abbreviated weekday name. 

40292 %A Replaced by the locale's full weekday name. 

40293 %b Replaced by the locale's abbreviated month name. 

40294 %B Replaced by the locale's full month name. 

40295 %c Replaced by the locale's appropriate date and time representation. 

40296 cx %C Replaced by the century number (the year divided by 100 and truncated to an integer) 

40297 as a decimal number [00-99]. 

40298 %d Replaced by the day of the month as a decimal number [01,31]. 

40299 cx %D Same as %m/%d/%y. 

40300 cx %e Replaced by the day of the month as a decimal number [1,31]; a single digit is preceded 

40301 by a space. 

40302 cx %h Same as %b. 

40303 %H Replaced by the hour (24-hour clock) as a decimal number [00,23]. 

40304 %I Replaced by the hour (12-hour clock) as a decimal number [01,12]. 

40305 %/ Replaced by the day of the year as a decimal number [001,366]. 

40306 %m Replaced by the month as a decimal number [01,12]. 

40307 %M Replaced by the minute as a decimal number [00,59]. 

40308 cx %n Replaced by a <newline> character. 

40309 %p Replaced by the locale's equivalent of either a.m. or p.m. 

40310 cx %r Replaced by the time in a.m. and p.m. notation; in the POSIX locale this is equivalent to 

40311 %I:%M:%S %p. 
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40312 cx %R Replaced by the time in 24 hour notation (%H:%M). 

40313 %S Replaced by the second as a decimal number [00,61]. 

40314 cx %t Replaced by a <tab> character. 

40315 cx %T Replaced by the time (%H:%M:%S). 

40316 °/ou Replaced by the weekday as a decimal number [1,7], with 1 representing Monday. 

40317 %U Replaced by the week number of the year (Sunday as the first day of the week) as a 

40318 decimal number [00,53]. 

40319 %V Replaced by the week number of the year (Monday as the first day of the week) as a 

40320 decimal number [01,53]. If the week containing 1 January has four or more days in the 

40321 new year, then it is considered week 1. Otherwise, it is the last week of the previous 

40322 year, and the next week is week 1. 

40323 %w Replaced by the weekday as a decimal number [0,6], with 0 representing Sunday. 

40324 %W Replaced by the week number of the year (Monday as the first day of the week) as a 

40325 decimal number [00,53]. All days in a new year preceding the first Monday are 

40326 considered to be in week 0. 

40327 %x Replaced by the locale's appropriate date representation. 

40328 %X Replaced by the locale's appropriate time representation. 

40329 %y Replaced by the year without century as a decimal number [00,99]. 

40330 %Y Replaced by the year with century as a decimal number. 

40331 %Z Replaced by the timezone name or abbreviation, or by no bytes if no timezone 

40332 information exists. 

40333 %% Replaced by' %'. 

40334 If a conversion specification does not correspond to any of the above, the behavior is undefined. 


40335 Notes to Reviewers 

40336 This section with side shading will not appear in the final copy. - Ed. 

40337 Dl, XSH, ERN 353 proposes we add %g and %G as proposed in C9x. 

40338 Modified Conversion Specifiers 

40339 cx Some conversion specifiers can be modified by the E or O modifier characters to indicate that an 

40340 alternative format or specification should be used rather than the one normally used by the 

40341 unmodified conversion specifier. If the alternative format or specification does not exist for the 

40342 current locale, (see ERA in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

40343 Section 7.3.5, LC_TIME) the behavior shall be as if the unmodified conversion specification were I 

40344 used. 

40345 %Ec Replaced by the locale's alternative appropriate date and time representation. 

40346 

40347 

40348 

40349 %EX Replaced by the locale's alternative time representation. 


%EC Replaced by the name of the base year (period) in the locale's alternative 
representation. 

%Ex Replaced by the locale's alternative date representation. 
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40350 

40351 

40352 

40353 

40354 

40355 

40356 

40357 

40358 

40359 

40360 

40361 

40362 

40363 

40364 

40365 

40366 

40367 

40368 

40369 

40370 

40371 

40372 

40373 

40374 

40375 

40376 

40377 

40378 

40379 

40380 

40381 

40382 

40383 

40384 

40385 

40386 

40387 

40388 

40389 

40390 

40391 


%Ey Replaced by the offset from %EC (year only) in the locale's alternative representation. 

%EY Replaced by the full alternative year representation. 

%Od Replaced by the day of the month, using the locale's alternative numeric symbols, filled 
as needed with leading zeros if there is any alternative symbol for zero; otherwise, with 
leading spaces. 

%Oe Replaced by the day of the month, using the locale's alternative numeric symbols, filled 
as needed with leading spaces. 

%OH Replaced by the hour (24-hour clock) using the locale's alternative numeric symbols. 

%OI Replaced by the hour (12-hour clock) using the locale's alternative numeric symbols. 

%Om Replaced by the month using the locale's alternative numeric symbols. 

%OM Replaced by the minutes using the locale's alternative numeric symbols. 

%OS Replaced by the seconds using the locale's alternative numeric symbols. 

%On Replaced by the weekday as a number in the locale's alternative representation 
(Monday=l). 

%OU Replaced by the week number of the year (Sunday as the first day of the week, rules 
corresponding to %U) using the locale's alternative numeric symbols. 

%OV Replaced by the week number of the year (Monday as the first day of the week, rules 
corresponding to %V) using the locale's alternative numeric symbols. 

%Oiv Replaced by the number of the weekday (Sunday=0) using the locale's alternative 
numeric symbols. 

%OW Replaced by the week number of the year (Monday as the first day of the week) using 
the locale's alternative numeric symbols. 

%Oy Replaced by the year (offset from %C) using the locale's alternative numeric symbols. 


RETURN VALUE 

If the total number of resulting bytes including the terminating null byte is not more than 
maxsize, strftime() shall return the number of bytes placed into the array pointed to by s, not 
including the terminating null byte. Otherwise, 0 shall be returned and the contents of the array 
are indeterminate. 

ERRORS 

No errors are defined. 

EXAMPLES 

Getting a Localized Date String 

The following example first sets the locale to the user's default. The locale information will be 
used in the nljanginfo () and strftime( ) functions. The nljanginfo () function returns the localized 
date string which specifies how the date is laid out. The strftime( ) function takes this information 
and, using the tm structure for values, places the date and time information into datestring. 

#include <time.h> 
tinclude <locale.h> 
tinclude <langinfo.h> 

struct tm *tm; 
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40392 

40393 

40394 

40395 

40396 

40397 

40398 

40399 

40400 

40401 

40402 

40403 

40404 

40405 

40406 

40407 

40408 

40409 

40410 

40411 

40412 

40413 

40414 

40415 

40416 

40417 

40418 

40419 

40420 

40421 

40422 

40423 

40424 

40425 

40426 

40427 

40428 

40429 

40430 

40431 

40432 

40433 


char datestring[256] ; 
setlocale (LC_ALL, 

strftime (datestring, sizeof (datestring) , nl_langinfo (D_T_FMT), tm); 

APPLICATION USAGE 

The range of values for %S is [00,61] rather than [00,59] to allow for the occasional leap second 
and even more infrequent double leap second. 

Some of the conversion specifications marked EX are duplicates of others. They are included for 
compatibility with nljcxtime () and nl_ascxtime (), which were published in Issue 2. 

Applications should use %Y (4-digit years) in preference to %y (2-digit years). 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

asctime (), clock(), ctime(), difftime (), gmtime(), localtime(), mktime(), strptime (), time(), utime(), 
the System Interface Definitions volume of IEEE Std. 1003.1-200x, <time.h> 

CHANGE HISTORY 

First released in Issue 3. 


Issue 4 

The DESCRIPTION is expanded to describe modified conversion specifiers. 

%C, %e, %R, %», and %V are added to the list of valid conversion specifications. 

The DESCRIPTION and RETURN VALUE sections are changed to make it clear when the 
function uses byte values rather than (possibly multi-byte) character values. 

The following changes are incorporated for alignment with the ISO C standard: 

• The type of argument format is changed from char* to const char*, and the type of argument 
timptr is changed from struct tm* to const struct tm*. 

• In the description of the %Z conversion specification, the words "or abbreviation" are added 
to indicate that strftime () does not necessarily return a full timezone name. 

Issue 5 

The description of %OV is changed to be consistent with %V and defines Monday as the first 
day of the week. 

The description of %Oxj is clarified. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The Open Group corrigenda item U033/8 has been applied. The %V conversion specifier is 
changed from "Otherwise, it is week 53 of the previous year, and the next week is week 1" to 
"Otherwise, it is the last week of the previous year, and the next week is week 1". 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 
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40435 

40436 


• The %C, %D, %e, %h, %n, %r, %R, %t, and %T conversion specifiers are added. 

• The modified conversion specifiers are added for consistency with the ISO POSIX-2 standard 
date utility. 
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40437 NAME 

40438 strlen — get string length 

40439 SYNOPSIS 

40440 tinclude <string.h> 

40441 size_t strlen (const char *s) ; 

40442 DESCRIPTION 

40443 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

40444 conflict between the requirements described here and the ISO C standard is unintentional. This I 

40445 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

40446 The strlen () function shall compute the number of bytes in the string to which s points, not 

40447 including the terminating null byte. 

40448 RETURN VALUE 

40449 The strlen () function shall return the length of s; no return value shall be reserved to indicate an 

40450 error. 

40451 ERRORS 

40452 No errors are defined. 

40453 EXAMPLES 

40454 Getting String Lengths 

40455 The following example sets the maximum length of key and data by using strlen () to get the 

40456 lengths of those strings. 

40457 #include <string.h> 

40458 

40459 struct element { 

40460 char *key; 

40461 char *data; 

40462 } ; 

40463 

40464 char *key, *data; 

40465 int len; 

40466 *keylength = *datalength = 0; 

40467 

40468 if ( (len = strlen (key) ) > *keylength) 

40469 *keylength = len; 

40470 if ( (len = strlen (data) ) > *datalength) 

40471 *datalength = len; 

40472 

40473 APPLICATION USAGE 

40474 None. 

40475 RATIONALE 

40476 None. 

40477 FUTURE DIRECTIONS 

40478 None. 
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40479 

40480 

40481 

40482 

40483 

40484 

40485 

40486 

40487 

40488 

40489 

40490 

40491 


SEE ALSO 

The System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The DESCRIPTION is changed to make it clear that the function works in units of bytes rather 
than (possibly multi-byte) characters. 

The following change is incorporated for alignment with the ISO C standard: 

• The type of argument s is changed from char’'' to const char*. 

Issue 5 

The RETURN VALUE section is updated to indicate that strlen() returns the length of s, and not 
s itself as was previously stated. 
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40492 NAME 

40493 strncasecmp — case-insensitive string comparison 

40494 SYNOPSIS 

40495 xsi #include <strings.h> 

40496 int strncasecmp (const char *sl, const char *s2, 

40497 

40498 DESCRIPTION 

40499 Refer to strcasecmp (). 


size_t n); 
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40500 NAME 

40501 strncat — concatenate a string with part of another 

40502 SYNOPSIS 

40503 #include <string.h> 

40504 char *strncat (char *sl, const char *s2, size_t n) ; 

40505 DESCRIPTION 

40506 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

40507 conflict between the requirements described here and the ISO C standard is unintentional. This I 

40508 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

40509 The strncat () function shall append not more than n bytes (a null byte and bytes that follow it 

40510 are not appended) from the array pointed to by s2 to the end of the string pointed to by si . The 

40511 initial byte of s2 overwrites the null byte at the end of si. A terminating null byte is always 

40512 appended to the result. If copying takes place between objects that overlap, the behavior is 

40513 undefined. 

40514 RETURN VALUE 

40515 The strncat () function shall return si ; no return value shall be reserved to indicate an error. 

40516 ERRORS 

40517 No errors are defined. 

40518 EXAMPLES 

40519 None. 

40520 APPLICATION USAGE 

40521 None. 

40522 RATIONALE 

40523 None. 

40524 FUTURE DIRECTIONS 

40525 None. 

40526 SEE ALSO 

40527 strcat( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

40528 CHANGE HISTORY 

40529 First released in Issue 1. 

40530 Derived from Issue 1 of the SVID. 

40531 Issue 4 

40532 The DESCRIPTION is changed to make it clear that the function manipulates bytes rather than 

40533 (possibly multi-byte) characters. 

40534 The following change is incorporated for alignment with the ISO C standard: 

40535 • The type of argument s2 is changed from char* to const char*. 
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40536 

40537 

40538 

40539 

40540 

40541 

40542 

40543 

40544 

40545 

40546 

40547 

40548 

40549 

40550 

40551 

40552 

40553 

40554 

40555 

40556 

40557 

40558 

40559 

40560 

40561 

40562 

40563 

40564 

40565 

40566 

40567 

40568 

40569 

40570 

40571 

40572 

40573 

40574 

40575 


NAME 

strncmp — compare part of two strings 

SYNOPSIS 

#include <string.h> 

int strncmp(const char *sl, const char *s2, size_t n ); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The strncmp () function shall compare not more than n bytes (bytes that follow a null byte are not 
compared) from the array pointed to by si to the array pointed to by s2. 

The sign of a non-zero return value is determined by the sign of the difference between the 
values of the first pair of bytes (both interpreted as type unsigned char) that differ in the strings 
being compared. 

RETURN VALUE 

Upon successful completion, strncmp () shall return an integer greater than, equal to, or less than 
0, if the possibly null-terminated array pointed to by si is greater than, equal to, or less than the 
possibly null-terminated array pointed to by s2 respectively. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

strcmpi ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The DESCRIPTION is changed to make it clear that the function manipulates bytes rather than 
(possibly multi-byte) characters. 

The following change is incorporated for alignment with the ISO C standard: 

• The type of arguments si and s2 are changed from char* to const char*. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 
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40576 NAME 

40577 strncpy — copy part of a string 

40578 SYNOPSIS 

40579 #include <string.h> 

40580 char *strncpy (char *sl, const char *s2, size_t n) ; 

40581 DESCRIPTION 

40582 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

40583 conflict between the requirements described here and the ISO C standard is unintentional. This I 

40584 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

40585 The strncpy () function shall copy not more than n bytes (bytes that follow a null byte are not 

40586 copied) from the array pointed to by s2 to the array pointed to by si . If copying takes place 

40587 between objects that overlap, the behavior is undefined. 

40588 If the array pointed to by s2 is a string that is shorter than n bytes, null bytes shall be appended 

40589 to the copy in the array pointed to by si , until n bytes in all are written. 

40590 RETURN VALUE 

40591 The strncpy () function shall return si ; no return value is reserved to indicate an error. 

40592 ERRORS 

40593 No errors are defined. 

40594 EXAMPLES 

40595 None. 

40596 APPLICATION USAGE 

40597 Character movement is performed differently in different implementations. Thus, overlapping 

40598 moves may yield surprises. 

40599 If there is no null byte in the first n bytes of the array pointed to by s2, the result is not null- 

40600 terminated. 

40601 RATIONALE 

40602 None. 

40603 FUTURE DIRECTIONS 

40604 None. 

40605 SEE ALSO 

40606 strcpy( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

40607 CHANGE HISTORY 

40608 First released in Issue 1. 

40609 Derived from Issue 1 of the SVID. 

40610 Issue 4 

40611 The DESCRIPTION is changed to make it clear that the function manipulates bytes rather than 

40612 (possibly multi-byte) characters. 

40613 The following change is incorporated for alignment with the ISO C standard: 

40614 • The type of argument s2 is changed from char* to const char*. 
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40615 

40616 

40617 

40618 

40619 

40620 

40621 

40622 

40623 

40624 

40625 

40626 

40627 

40628 

40629 

40630 

40631 

40632 

40633 

40634 

40635 

40636 

40637 

40638 

40639 

40640 

40641 

40642 

40643 

40644 

40645 

40646 

40647 

40648 


NAME 

strpbrk — scan string for byte 

SYNOPSIS 

#include <string.h> 

char *strpbrk(const char *sl, const char *s2); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The strpbrk () function shall locate the first occurrence in the string pointed to by si of any byte 
from the string pointed to by s2. 

RETURN VALUE 

Upon successful completion, strpbrk () shall return a pointer to the byte or a null pointer if no 
byte from s2 occurs in si. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

strchr (), strrchr (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The DESCRIPTION and RETURN VALUE sections are changed to make it clear that the function 
works in units of bytes rather than (possibly multi-byte) characters. 

The following change is incorporated for alignment with the ISO C standard: 

• The type of arguments si and s2 is changed from char* to const char*. 
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40649 

40650 

40651 

40652 

40653 

40654 

40655 

40656 

40657 

40658 

40659 

40660 

40661 

40662 

40663 

40664 

40665 

40666 

40667 

40668 

40669 

40670 

40671 

40672 

40673 

40674 

40675 

40676 

40677 

40678 

40679 

40680 

40681 

40682 

40683 

40684 

40685 

40686 

40687 


NAME 

strptime — date and time conversion 

SYNOPSIS 

xsi tinclude <time.h> 

char *strptime(const char *buf, const char * format, struct tm *tm); 

DESCRIPTION 

The strptime ( ) function shall convert the character string pointed to by buf to values which are 
stored in the tm structure pointed to by tm, using the format specified by format. 

The format is composed of zero or more directives. Each directive is composed of one of the 
following: one or more white-space characters (as specified by isspace( )); an ordinary character 
(neither '%' nor a white-space character); or a conversion specification. Each conversion 
specification is composed of a ' %' character followed by a conversion character which specifies 
the replacement required. The application shall ensure that there is white-space or other non- I 
alphanumeric characters between any two conversion specifications. The following conversion I 
specifications are supported: I 

%a The day of the week, using the locale's weekday names; either the abbreviated or full 
name may be specified. 

%A The same as %a. 

%b The month, using the locale's month names; either the abbreviated or full name may be 
specified. 

%B The same as %b. 

%c Replaced by the locale's appropriate date and time representation. 

%C The century number [0,99]; leading zeros are permitted but not required. 

%d The day of the month [1,31]; leading zeros are permitted but not required. 

%D The date as %m / %d / %y. 

%e The same as %d. 

%h The same as %b. 

%H The hour (24-hour clock) [0,23]; leading zeros are permitted but not required. 

%I The hour (12-hour clock) [1,12]; leading zeros are permitted but not required. 

%j The day number of the year [1,366]; leading zeros are permitted but not required. 

%m The month number [1,12]; leading zeros are permitted but not required. 

%M The minute [0-59]; leading zeros are permitted but not required. 

%n Any white space. 

%p The locale's equivalent of a.m or p.m. 

%r 12-hour clock time using the AM/PM notation if t_fmt_ampm is not an empty string in 

the LC_TIME portion of the current locale; in the POSIX locale, this is equivalent to 
%I:%M:%S %p. 

%R The time as %H:%M. 
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40688 

40689 

40690 

40691 

40692 

40693 

40694 

40695 

40696 

40697 

40698 

40699 

40700 

40701 

40702 

40703 

40704 

40705 

40706 

40707 

40708 

40709 

40710 

40711 

40712 

40713 

40714 

40715 

40716 

40717 

40718 

40719 

40720 

40721 

40722 

40723 

40724 

40725 


%S The seconds [0,61]; leading zeros are permitted but not required. 

%t Any white space. 

%T The time as %H:%M:%S. 

%U The week number of the year (Sunday as the first day of the week) as a decimal number 
[00,53]; leading zeros are permitted but not required. 

%iv The weekday as a decimal number [0,6], with 0 representing Sunday; leading zeros are 
permitted but not required. 

%W The week number of the year (Monday as the first day of the week) as a decimal 
number [00,53]; leading zeros are permitted but not required. 

%x The date, using the locale's date format. 

%X The time, using the locale's time format. 

%y The year within century. When a century is not otherwise specified, values in the range 
69-99 refer to years in the twentieth century (1969 to 1999 inclusive); values in the range 
00-68 refer to years in the twenty-first century (2000 to 2068 inclusive); leading zeros 
are permitted but not required. 

%Y The year, including the century (for example, 1988). 

% % Replaced by ' %'. 

Modified Directives 

Some directives can be modified by the E and O modifier characters to indicate that an 
alternative format or specification should be used rather than the one normally used by the 
unmodified directive. If the alternative format or specification does not exist in the current 
locale, the behavior shall be as if the unmodified directive were used. 

%Ec The locale's alternative appropriate date and time representation. 

%EC The name of the base year (period) in the locale's alternative representation. 

%Ex The locale's alternative date representation. 

%EX The locale's alternative time representation. 

%E\j The offset from %EC (year only) in the locale's alternative representation. 

%EY The full alternative year representation. 

%Od The day of the month using the locale's alternative numeric symbols; leading zeros are 
permitted but not required. 

%Oe The same as %Od. 

%OH The hour (24-hour clock) using the locale's alternative numeric symbols. 

%Ot The hour (12-hour clock) using the locale's alternative numeric symbols. 

%Om The month using the locale's alternative numeric symbols. 

%OM The minutes using the locale's alternative numeric symbols. 

%OS The seconds using the locale's alternative numeric symbols. 

%OLt The week number of the year (Sunday as the first day of the week) using the locale's 
alternative numeric symbols. 
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40727 

40728 

40729 


%0 w The number of the weekday (Sunday=0) using the locale's alternative numeric symbols. 

%OW The week number of the year (Monday as the first day of the week) using the locale's 

alternative numeric symbols. 

%Oxj The year (offset from %C) using the locale's alternative numeric symbols. 


40730 A directive composed of white-space characters is executed by scanning input up to the first 

40731 character that is not white-space (which remains unscanned), or until no more characters can be 

40732 scanned. 


40733 A directive that is an ordinary character is executed by scanning the next character from the 

40734 buffer. If the character scanned from the buffer differs from the one comprising the directive, the 

40735 directive fails, and the differing and subsequent characters remain unscanned. 

40736 A series of directives composed of %n, %f, white-space characters, or any combination is 

40737 executed by scanning up to the first character that is not white space (which remains 

40738 unscanned), or until no more characters can be scanned. 

40739 Any other conversion specification is executed by scanning characters until a character matching 

40740 the next directive is scanned, or until no more characters can be scanned. These characters, 

40741 except the one matching the next directive, are then compared to the locale values associated 

40742 with the conversion specifier. If a match is found, values for the appropriate tm structure 

40743 members are set to values corresponding to the locale information. Case is ignored when 

40744 matching items in buf such as month or weekday names. If no match is found, strptime () fails 

40745 and no more characters are scanned. 


40746 RETURN VALUE 

40747 Upon successful completion, strptime( ) shall return a pointer to the character following the last 

40748 character parsed. Otherwise, a null pointer shall be returned. 

40749 ERRORS 

40750 No errors are defined. 

40751 EXAMPLES 

40752 None. 

40753 APPLICATION USAGE 

40754 Several "same as" formats and the special processing of white-space characters are provided in 

40755 order to ease the use of identical/orwzflf strings for strftime( ) and strptime (). 

40756 Applications should use %Y (4-digit years) in preference to %y (2-digit years). 

40757 RATIONALE 

40758 None. 

40759 FUTURE DIRECTIONS 

40760 The strptime () function is expected to be mandatory in the next version of this volume of 

40761 IEEE Std. 1003.1-200x. 

40762 SEE ALSO 

40763 scanf (), strftime (), time( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

40764 <time.h> 

40765 CHANGE HISTORY 

40766 First released in Issue 4. 
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40767 

40768 

40769 

40770 

40771 

40772 

40773 

40774 


Issue 5 

Moved from ENHANCED I18N to BASE. 

The [ENOSYS] error is removed. 

The exact meaning of the %y and %Oy specifiers are clarified in the DESCRIPTION. 

Issue 6 

The Open Group corrigenda item U033/5 has been applied. The %r specifier description is 
reworded. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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40775 

40776 

40777 

40778 

40779 

40780 

40781 

40782 

40783 

40784 

40785 

40786 

40787 

40788 

40789 

40790 

40791 

40792 

40793 

40794 

40795 

40796 

40797 

40798 

40799 

40800 

40801 

40802 

40803 

40804 

40805 

40806 

40807 

40808 

40809 

40810 

40811 

40812 

40813 

40814 

40815 

40816 


NAME 

strrchr — string scanning operation 

SYNOPSIS 

#include <string.h> 

char *strrchr(const char *s, int c) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

cx The strrchr () function shall locate the last occurrence of c (converted to an unsigned char) in the 

string pointed to by s. The terminating null byte is considered to be part of the string. 

RETURN VALUE 

Upon successful completion, strrchr( ) shall return a pointer to the byte or a null pointer if c does 
not occur in the string. 

ERRORS 

No errors are defined. 

EXAMPLES 

Finding the Base Name of a File 

The following example uses strrchr( ) to get a pointer to the base name of a file. The strrchr () 
function searches backwards through the name of the file to find the last ' /' character in name. 
This pointer (plus one) will point to the base name of the file. 

#include <string.h> 

const char *name; 
char *basename; 

basename = strrchr (name, '/') + 1; 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

strchr( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The DESCRIPTION and RETURN VALUE sections are changed to make it clear that the function 
works in units of bytes rather than (possibly multi-byte) characters. 
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40817 

40818 


The following change is incorporated for alignment with the ISO C standard: 
• The type of argument s is changed from char* to const char*. 
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40819 NAME 

40820 strspn — get length of a substring 

40821 SYNOPSIS 

40822 #include <string.h> 

40823 size_t strspn (const char *sl, const char *s2); 

40824 DESCRIPTION 

40825 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

40826 conflict between the requirements described here and the ISO C standard is unintentional. This I 

40827 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

40828 The strspn () function shall compute the length of the maximum initial segment of the string 

40829 pointed to by si which consists entirely of bytes from the string pointed to by s2. 

40830 RETURN VALUE 

40831 The strspn () function shall return the length of si ; no return value is reserved to indicate an 

40832 error. 

40833 ERRORS 

40834 No errors are defined. 

40835 EXAMPLES 

40836 None. 

40837 APPLICATION USAGE 

40838 None. 

40839 RATIONALE 

40840 None. 

40841 FUTURE DIRECTIONS 

40842 None. 

40843 SEE ALSO 

40844 strcspn(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

40845 CHANGE HISTORY 

40846 First released in Issue 1. 

40847 Derived from Issue 1 of the SVID. 

40848 Issue 4 

40849 The DESCRIPTION is changed to make it clear that the function works in units of bytes rather 

40850 than (possibly multi-byte) characters. 

40851 The following change is incorporated for alignment with the ISO C standard: 

40852 • The type of arguments si and s2 are changed from char* to const char*. 

40853 Issue 5 

40854 The RETURN VALUE section is updated to indicate that strspn () returns the length of s, and not 

40855 s itself as was previously stated. 
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40856 NAME 

40857 strstr — find a substring 

40858 SYNOPSIS 

40859 #include <string.h> 

40860 char *strstr (const char *sl, const char *s2); 

40861 DESCRIPTION 

40862 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

40863 conflict between the requirements described here and the ISO C standard is unintentional. This I 

40864 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

40865 The strstr() function shall locate the first occurrence in the string pointed to by si of the 

40866 sequence of bytes (excluding the terminating null byte) in the string pointed to by s2. 

40867 RETURN VALUE 

40868 Upon successful completion, strstr( ) shall return a pointer to the located string or a null pointer 

40869 if the string is not found. 

40870 If s2 points to a string with zero length, the function shall return si. 

40871 ERRORS 

40872 No errors are defined. 

40873 EXAMPLES 

40874 None. 

40875 APPLICATION USAGE 

40876 None. 

40877 RATIONALE 

40878 None. 

40879 FUTURE DIRECTIONS 

40880 None. 

40881 SEE ALSO 

40882 strclir( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

40883 CHANGE HISTORY 

40884 First released in Issue 3. 

40885 Entry included for alignment with the ANSI C standard. 

40886 Issue 4 

40887 The DESCRIPTION is changed to make it clear that the function works in units of bytes rather 

40888 than (possibly multi-byte) characters. 

40889 The following change is incorporated for alignment with the ISO C standard: 

40890 • The type of arguments si and s2 are changed from char* to const char*. 
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40891 NAME 

40892 strtod — convert string to a double-precision number 

40893 SYNOPSIS 

40894 #include <stdlib.h> 

40895 double strtod (const char *str, char **endptr ); 

40896 DESCRIPTION 

40897 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

40898 conflict between the requirements described here and the ISO C standard is unintentional. This I 

40899 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

40900 The strtod() function shall convert the initial portion of the string pointed to by str to type 

40901 double representation. First it decomposes the input string into three parts: 

40902 1. An initial, possibly empty, sequence of white-space characters (as specified by isspace ()) 

40903 2. A subject sequence interpreted as a floating-point constant 

40904 3. A final string of one or more unrecognized characters, including the terminating null byte 

40905 of the input string 

40906 Then it attempts to convert the subject sequence to a floating-point number, and returns the 

40907 result. 

40908 The expected form of the subject sequence is an optional ' + ' or sign, then a non-empty 

40909 sequence of digits optionally containing a radix character, then an optional exponent part. An 

40910 exponent part consists of e or E, followed by an optional sign, followed by one or more decimal 

40911 digits. The subject sequence is defined as the longest initial subsequence of the input string, 

40912 starting with the first non-white-space character that is of the expected form. The subject 

40913 sequence is empty if the input string is empty or consists entirely of white-space characters, or if 

40914 the first character that is not white-space is other than a sign, a digit, or a radix character. 

40915 If the subject sequence has the expected form, the sequence starting with the first digit or the 

40916 radix character (whichever occurs first) is interpreted as a floating constant of the C language, 

40917 except that the radix character is used in place of a period, and that if neither an exponent part 

40918 nor a radix character appears, a radix character is assumed to follow the last digit in the string. If 

40919 the subject sequence begins with a minus sign, the value resulting from the conversion is 

40920 negated. A pointer to the final string is stored in the object pointed to by endptr, provided that 

40921 endptr is not a null pointer. 

40922 cx The radix character is defined in the program's locale (category LC_NUMERIC). In the POSIX 

40923 locale, or in a locale where the radix character is not defined, the radix character defaults to a 

40924 period (' . 

40925 cx In other than the C or POSIX locales, other implementation-dependent subject sequences may be 

40926 accepted. 

40927 If the subject sequence is empty or does not have the expected form, no conversion is performed; 

40928 the value of str is stored in the object pointed to by endptr, provided that endptr is not a null 

40929 pointer. 

40930 The strtod( ) function shall not change the setting of err no if successful. 

40931 Because 0 is returned on error and is also a valid return on success, an application wishing to 

40932 check for error situations should set errno to 0, then call s trtod( ), then check errno. 
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40933 

40934 

40935 

40936 

40937 

40938 

40939 

40940 

40941 

40942 

40943 

40944 

40945 

40946 

40947 

40948 

40949 

40950 

40951 

40952 

40953 

40954 

40955 

40956 

40957 

40958 

40959 

40960 

40961 

40962 

40963 

40964 

40965 

40966 

40967 

40968 

40969 

40970 


RETURN VALUE 

Upon successful completion, strtod() shall return the converted value. If no conversion could be 
cx performed, 0 shall be returned, and errno may be set to [EINVAL]. 

If the correct value is outside the range of representable values, ±HUGE_VAL shall be returned 
(according to the sign of the value), and errno shall be set to [ERANGE]. 

If the correct value would cause an underflow, 0 shall be returned and errno set to [ERANGE]. 

ERRORS 

The strtod () function shall fail if: 

[ERANGE] The value to be returned would cause overflow or underflow. 

The strtod () function may fail if: 
cx [EINVAL] No conversion could be performed. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

isspace(), localeconv(), scanf(), setlocale(), strtol(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <stdlib.h>, the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Chapter 7, Locale I 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The DESCRIPTION is changed to make it clear when the function manipulates bytes and when 
it manipulates characters. 

The [EINVAL] error is added to the ERRORS section and marked as an extension. 

The following changes are incorporated for alignment with the ISO C standard: 

• The function is no longer marked as an extension. 

• The type of argument str is changed from char* to const char*. 

• The name of the second argument is changed from ptr to endptr. 

• The precise conditions under which the [ERANGE] error can be set have been defined in the 
RETURN VALUE section. 

Issue 5 

The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 
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40971 

40972 

40973 

40974 

40975 

40976 


Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 
added if no conversion could be performed. 
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40977 NAME 

40978 strtok, strtok_r — split string into tokens 

40979 SYNOPSIS 

40980 tinclude <string.h> 

40981 char *strtok(char *sl, const char *s2); 

40982 TSF char *strtok_r(char *s, const char *sep, char **lasts); 

40983 

40984 DESCRIPTION 

40985 cx For strtok(): The functionality described on this reference page is aligned with the ISOC 

40986 standard. Any conflict between the requirements described here and the ISO C standard is I 

40987 unintentional. This volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

40988 A sequence of calls to strtok () breaks the string pointed to by si into a sequence of tokens, each 

40989 of which is delimited by a byte from the string pointed to by s2 . The first call in the sequence has 

40990 si as its first argument, and is followed by calls with a null pointer as their first argument. The 

40991 separator string pointed to by s2 may be different from call to call. 

40992 The first call in the sequence searches the string pointed to by si for the first byte that is not 

40993 contained in the current separator string pointed to by s2 . If no such byte is found, then there 

40994 are no tokens in the string pointed to by si and strtok() returns a null pointer. If such a byte is 

40995 found, it is the start of the first token. 

40996 The strtok () function then searches from there for a byte that is contained in the current 

40997 separator string. If no such byte is found, the current token extends to the end of the string 

40998 pointed to by si , and subsequent searches for a token shall return a null pointer. If such a byte is 

40999 found, it is overwritten by a null byte, which terminates the current token. The strtok () function 

41000 saves a pointer to the following byte, from which the next search for a token shall start. 

41001 Each subsequent call, with a null pointer as the value of the first argument, starts searching from 

41002 the saved pointer and behaves as described above. 

41003 The implementation shall behave as if no function defined in this volume of 

41004 IEEE Std. 1003.1-200x calls strtok( ). 

41005 cx The strtok( ) function need not be reentrant. A function that is not required to be reentrant is not 

41006 required to be thread-safe. 

41007 tsf The strtok_r( ) function considers the null-terminated string s as a sequence of zero or more text 

41008 tokens separated by spans of one or more characters from the separator string sep. The 

41009 argument lasts points to a user-provided pointer which points to stored information necessary 

41010 for strtok_r( ) to continue scanning the same string. 

41011 In the first call to strtok_r( ), s points to a null-terminated string, sep to a null-terminated string of 

41012 separator characters, and the value pointed to by lasts is ignored. The strtok_r( ) function returns 

41013 a pointer to the first character of the first token, writes a null character into s immediately 

41014 following the returned token, and updates the pointer to which lasts points. 

41015 In subsequent calls, s is a NULL pointer and lasts shall be unchanged from the previous call so 

41016 that subsequent calls shall move through the string s, returning successive tokens until no 

41017 tokens remain. The separator string sep may be different from call to call. When no token 

41018 remains in s, a NULL pointer is returned. 
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41019 RETURN VALUE 

41020 Upon successful completion, strtok( ) shall return a pointer to the first byte of a token. Otherwise, 

41021 if there is no token, strtok( ) shall return a null pointer. 

41022 tsf The strtok_r() function shall return a pointer to the token found, or a NULL pointer when no 

41023 token is found. 

41024 ERRORS 

41025 No errors are defined. 

41026 EXAMPLES 

41027 Searching for Word Separators 

41028 The following example searches for tokens separated by space characters. 

41029 tinclude <string.h> 

41030 

41031 char *token; 

41032 char *line = "LINE TO BE SEPARATED"; 

41033 char * search = " 

41034 /* Token will point to "LINE" . */ 

41035 token = strtok (line, search) ; 

41036 /* Token will point to "TO" . */ 

41037 token = strtok (NULL, search) ; 

41038 Breaking a Line 

41039 The following example uses strtok( ) to break a line into two character strings separated by any 

41040 combination of <space>s, <tab>s, or <newline>s. 

41041 #include <string.h> 

41042 

41043 struct element { 

41044 char *key; 

41045 char *data; 

41046 }; 

41047 

41048 char line [LINE_MAX] ; 

41049 char *key, *data; 

41050 

41051 key = strtok (line, " \n"); 

41052 data = strtok (NULL, " \n"); 

41053 

41054 APPLICATION USAGE 

41055 The strtok_r() function is thread-safe and stores its state in a user-supplied buffer instead of 

41056 possibly using a static data area that may be overwritten by an unrelated call from another 

41057 thread. 

41058 RATIONALE 

41059 The strtok( ) function searches for a separator string within a larger string. It returns a pointer to 

41060 the last substring between separator strings. This function uses static storage to keep track of 

41061 the current string position between calls. The new function, strtok_r(), takes an additional 

41062 argument, lasts, to keep track of the current position in the string. 
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41063 

41064 

41065 

41066 

41067 

41068 

41069 

41070 

41071 

41072 

41073 

41074 

41075 

41076 

41077 

41078 

41079 

41080 

41081 

41082 

41083 

41084 


FUTURE DIRECTIONS 

None. 

SEE ALSO 

The System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The DESCRIPTION is changed to make it clear that the function manipulates bytes rather than 
(possibly multi-byte) characters. 

The following changes are incorporated for alignment with the ISO C standard: 

• The function is no longer marked as an extension. 

• The type of argument s2 is changed from char* to const char*. 

Issue 5 

The strtok_r () function is included for alignment with the POSIX Threads Extension. 

A note indicating that the strtok () function need not be reentrant is added to the DESCRIPTION. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The strtok_r () function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS option. 

In the DESCRIPTION, the note about reentrancy is expanded to cover thread-safety. 

The APPLICATION USAGE section is updated to include a note on the thread-safe function and 
its avoidance of possibly using a static data area. 
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41085 NAME 

41086 strtol — convert string to a long integer 

41087 SYNOPSIS 

41088 #include <stdlib.h> 

41089 long int strtol (const char *str, char **endptr, int base); 

41090 DESCRIPTION 

41091 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

41092 conflict between the requirements described here and the ISO C standard is unintentional. This I 

41093 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

41094 The strtol () function shall convert the initial portion of the string pointed to by str to a type long 

41095 int representation. First it decomposes the input string into three parts: 

41096 1. An initial, possibly empty, sequence of white-space characters (as specified by isspace ()) 

41097 2. A subject sequence interpreted as an integer represented in some radix determined by the 

41098 value of base 

41099 3. A final string of one or more unrecognized characters, including the terminating null byte 

41100 of the input string. 

41101 Then it attempts to convert the subject sequence to an integer, and returns the result. 

41102 If the value of base is 0, the expected form of the subject sequence is that of a decimal constant, 

41103 octal constant, or hexadecimal constant, any of which may be preceded by a ' + ' or ' - ' sign. A 

41104 decimal constant begins with a non-zero digit, and consists of a sequence of decimal digits. An 

41105 octal constant consists of the prefix ' 0' optionally followed by a sequence of the digits ' 0' to 

41106 ' 1' only. A hexadecimal constant consists of the prefix "Ox" or "OX" followed by a sequence of 

41107 the decimal digits and letters ' a' (or ' A' ) to ' f (or ' F') with values 10 to 15 respectively. 

41108 If the value of base is between 2 and 36, the expected form of the subject sequence is a sequence 

41109 of letters and digits representing an integer with the radix specified by base, optionally preceded 

41110 by a ' + ' or sign. The letters from 'a' (or ' A' ) to ' z' (or ' Z' ) inclusive are ascribed the 

41111 values 10 to 35; only letters whose ascribed values are less than that of base are permitted. If the 

41112 value of base is 16, the characters "Ox" or "OX" may optionally precede the sequence of letters 

41113 and digits, following the sign if present. 

41114 The subject sequence is defined as the longest initial subsequence of the input string, starting 

41115 with the first non-white-space character that is of the expected form. The subject sequence 

41116 contains no characters if the input string is empty or consists entirely of white-space characters, 

41117 or if the first non-white-space character is other than a sign or a permissible letter or digit. 

41118 If the subject sequence has the expected form and the value of base is 0, the sequence of 

41119 characters starting with the first digit is interpreted as an integer constant. If the subject 

41120 sequence has the expected form and the value of base is between 2 and 36, it is used as the base 

41121 for conversion, ascribing to each letter its value as given above. If the subject sequence begins 

41122 with a minus sign, the value resulting from the conversion is negated. A pointer to the final 

41123 string is stored in the object pointed to by endptr, provided that endptr is not a null pointer. 

41124 cx In other than the C or POSIX locales, other implementation-dependent subject sequences may be 

41125 accepted. 

41126 If the subject sequence is empty or does not have the expected form, no conversion is performed; 

41127 the value of str is stored in the object pointed to by endptr, provided that endptr is not a null 

41128 pointer. 
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41129 

41130 

41131 

41132 

41133 

41134 

41135 

41136 

41137 

41138 

41139 

41140 

41141 

41142 

41143 

41144 

41145 

41146 

41147 

41148 

41149 

41150 

41151 

41152 

41153 

41154 

41155 

41156 

41157 

41158 

41159 

41160 

41161 

41162 

41163 

41164 

41165 

41166 

41167 

41168 


The strtol () function shall not change the setting of errno if successful. 

Because 0, {LONG_MIN}, and |LONG_MAX} are returned on error and are also valid returns on 
success, an application wishing to check for error situations should set errno to 0, then call 
strtol (), then check errno. 

RETURN VALUE 

Upon successful completion strtol () shall return the converted value, if any. If no conversion 
cx could be performed, 0 shall be returned and errno may be set to [EINVAL]. 

If the correct value is outside the range of representable values, |LONG_MAX} or |LONG_MIN} 
shall be returned (according to the sign of the value), and errno set to [ERANGE]. 

ERRORS 

The strtol () function shall fail if: 

[ERANGE] The value to be returned is not representable. 

The strtol () function may fail if: 
cx [EINVAL] The value of base is not supported. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

isalplm(), scanf(), strtod(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

<stdlib.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The DESCRIPTION is changed to make it clear when the function manipulates bytes and when 
it manipulates characters. 

In the RETURN VALUE section, text indicating that errno is set when 0 is returned is marked as 
an extension. 

The ERRORS section is updated in line with the RETURN VALUE section. 

The following changes are incorporated for alignment with the ISO C standard: 

• The function is no longer marked as an extension. 

• The type of argument str is changed from char’'' to const char*. 

• The name of the second argument is changed from ptr to endptr. 

• The DESCRIPTION is changed to indicate permitted forms of the subject sequence when base 
is 0. 
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41170 

41171 

41172 

41173 

41174 

41175 

41176 

41177 

41178 


• The RETURN VALUE section is changed to indicate that {LONG_MAX} or |LONG_MIN} is 
returned if the converted value is too large or too small. 

Issue 5 

The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 
added if no conversion could be performed. 
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41179 NAME 

41180 strtoul — convert string to an unsigned long 

41181 SYNOPSIS 

41182 #include <stdlib.h> 

41183 unsigned long int strtoul (const char *str, char **endptr, int base); 

41184 DESCRIPTION 

41185 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

41186 conflict between the requirements described here and the ISO C standard is unintentional. This I 

41187 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

41188 The strtoul () function shall convert the initial portion of the string pointed to by str to a type 

41189 unsigned long int representation. First it decomposes the input string into three parts: 

41190 1. An initial, possibly empty, sequence of white-space characters (as specified by isspace ()) 

41191 2. A subject sequence interpreted as an integer represented in some radix determined by the 

41192 value of base 

41193 3. A final string of one or more unrecognized characters, including the terminating null byte 

41194 of the input string 

41195 Then it attempts to convert the subject sequence to an unsigned integer, and returns the result. 

41196 If the value of base is 0, the expected form of the subject sequence is that of a decimal constant, 

41197 octal constant, or hexadecimal constant, any of which may be preceded by a ' +' or ' - ' sign. A 

41198 decimal constant begins with a non-zero digit, and consists of a sequence of decimal digits. An 

41199 octal constant consists of the prefix ' 0' optionally followed by a sequence of the digits ' 0' to 

41200 ' 1' only. A hexadecimal constant consists of the prefix "Ox" or "OX" followed by a sequence of 

41201 the decimal digits and letters ' a' (or ' A' ) to ' f (or ' F') with values 10 to 15 respectively. 

41202 If the value of base is between 2 and 36, the expected form of the subject sequence is a sequence 

41203 of letters and digits representing an integer with the radix specified by base, optionally preceded 

41204 by a ' + ' or sign. The letters from 'a' (or ' A' ) to ' z' (or ' Z' ) inclusive are ascribed the 

41205 values 10 to 35; only letters whose ascribed values are less than that of base are permitted. If the 

41206 value of base is 16, the characters "Ox" or "OX" may optionally precede the sequence of letters 

41207 and digits, following the sign if present. 

41208 The subject sequence is defined as the longest initial subsequence of the input string, starting 

41209 with the first non-white-space character that is of the expected form. The subject sequence 

41210 contains no characters if the input string is empty or consists entirely of white-space characters, 

41211 or if the first non-white-space character is other than a sign or a permissible letter or digit. 

41212 If the subject sequence has the expected form and the value of base is 0, the sequence of 

41213 characters starting with the first digit is interpreted as an integer constant. If the subject 

41214 sequence has the expected form and the value of base is between 2 and 36, it is used as the base 

41215 for conversion, ascribing to each letter its value as given above. If the subject sequence begins 

41216 with a minus sign, the value resulting from the conversion is negated. A pointer to the final 

41217 string is stored in the object pointed to by endptr, provided that endptr is not a null pointer. 

41218 cx In other than the C or POSIX locales, other implementation-dependent subject sequences may be 

41219 accepted. 

41220 If the subject sequence is empty or does not have the expected form, no conversion is performed; 

41221 the value of str is stored in the object pointed to by endptr, provided that endptr is not a null 

41222 pointer. 
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41223 The strtoul () function shall not change the setting of errno if successful. 

41224 Because 0 and |ULONG_MAX} are returned on error and are also valid returns on success, an 

41225 application wishing to check for error situations should set errno to 0, then call strtoul (), then 

41226 check errno. 

41227 RETURN VALUE 

41228 Upon successful completion strtoul () shall return the converted value, if any. If no conversion 

41229 cx could be performed, 0 shall be returned and errno may be set to [EINVAL]. If the correct value is 

41230 outside the range of representable values, |ULONG_MAX} shall be returned and errno set to 

41231 [ERANGE], 

41232 ERRORS 

41233 The strtoul () function shall fail if: 

41234 cx [EINVAL] The value of base is not supported. 

41235 [ERANGE] The value to be returned is not representable. 

41236 The strtoul () function may fail if: 

41237 cx [EINVAL] No conversion could be performed. 

41238 EXAMPLES 

41239 None. 

41240 APPLICATION USAGE 

41241 None. 

41242 RATIONALE 

41243 None. 

41244 FUTURE DIRECTIONS 

41245 None. 

41246 SEE ALSO 

41247 isalplm(), scanf(), strtod(), strtol(), the System Interface Definitions volume of 

41248 IEEE Std. 1003.1-200x, <stdlib.h> 

41249 CHANGE HISTORY 

41250 First released in Issue 4. 

41251 Derived from the ANSI C standard. 

41252 Issue 5 

41253 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 

41254 Issue 6 

41255 Extensions beyond the ISO C standard are now marked. 

41256 The following new requirements on POSIX implementations derive from alignment with the 

41257 Single UNIX Specification: 

41258 • The [EINVAL] error condition is added for when the value of base is not supported. 

41259 In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 

41260 added if no conversion could be performed. 
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41261 NAME 

41262 strxfrm — string transformation 

41263 SYNOPSIS 

41264 #include <string.h> 

41265 size_t strxfrm (char *sl, const char *s2, size_t n) ; 

41266 DESCRIPTION 

41267 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

41268 conflict between the requirements described here and the ISO C standard is unintentional. This I 

41269 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

41270 The strxfrm( ) function shall transform the string pointed to by s2 and places the resulting string 

41271 into the array pointed to by si. The transformation is such that if strcmp () is applied to two 

41272 transformed strings, it returns a value greater than, equal to, or less than 0, corresponding to the 

41273 result of strcoll () applied to the same two original strings. No more than n bytes are placed into 

41274 the resulting array pointed to by si , including the terminating null byte. If n is 0, si is permitted 

41275 to be a null pointer. If copying takes place between objects that overlap, the behavior is 

41276 undefined. 

41277 cx The strxfrm () function shall not change the setting of errno if successful. 

41278 Because no return value is reserved to indicate an error, an application wishing to check for error 

41279 situations should set errno to 0, then call strcoll (), then check errno. 

41280 RETURN VALUE 

41281 Upon successful completion, strxfrm() shall return the length of the transformed string (not 

41282 including the terminating null byte). If the value returned is n or more, the contents of the array 

41283 pointed to by si are indeterminate. 

41284 cx On error, strxfrm( ) may set errno but no return value is reserved to indicate an error. 

41285 ERRORS 

41286 The strxfrm () function may fail if: 

41287 cx [EINVAL] The string pointed to by the s2 argument contains characters outside the 

41288 domain of the collating sequence. 

41289 EXAMPLES 

41290 None. 

41291 APPLICATION USAGE 

41292 The transformation function is such that two transformed strings can be ordered by strcmp () as 

41293 appropriate to collating sequence information in the program's locale (category LCJZOLLATE). 

41294 The fact that when n is 0 si is permitted to be a null pointer is useful to determine the size of the 

41295 si array prior to making the transformation. 

41296 RATIONALE 

41297 None. 

41298 FUTURE DIRECTIONS 

41299 None. 

41300 SEE ALSO 

41301 strcmp( ), strcoll (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <string.h> 
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41302 

41303 

41304 

41305 

41306 

41307 

41308 

41309 

41310 

41311 

41312 

41313 

41314 

41315 

41316 

41317 

41318 

41319 

41320 

41321 

41322 


CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the ISO C standard. 

Issue 4 

The DESCRIPTION is changed to make it clear when the function manipulates byte values and 
when it manipulates characters. 

The sentence describing error returns in the RETURN VALUE section is marked as an extension, 
as is the [EINVAL] error. 

The APPLICATION USAGE section is expanded. 

The following changes are incorporated for alignment with the ISO C standard: 

• The function is no longer marked as an extension. 

• The type of argument s2 is changed from char* to const char*. 

Issue 5 

The DESCRIPTION is updated to indicate that errno does not changed if the function is 
successful. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 
added if no conversion could be performed. 
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41324 

41325 

41326 

41327 

41328 

41329 

41330 

41331 

41332 

41333 

41334 

41335 

41336 

41337 

41338 

41339 

41340 

41341 

41342 

41343 

41344 

41345 

41346 

41347 

41348 

41349 

41350 

41351 

41352 

41353 

41354 

41355 

41356 

41357 

41358 

41359 

41360 

41361 


NAME 

swab — swap bytes 

SYNOPSIS 

xsi tinclude <unistd.h> 

void swab(const void *src, void *dest, ssize_t mbytes); 


DESCRIPTION 

The swab{ ) function shall copy nbytes bytes, which are pointed to by src, to the object pointed to 
by dest, exchanging adjacent bytes. The nbytes argument should be even. If nbytes is odd, swab() 
copies and exchanges nbytes- 1 bytes and the disposition of the last byte is unspecified. If 
copying takes place between objects that overlap, the behavior is undefined. If nbytes is 
negative, siuab( ) does nothing. 

RETURN VALUE 

None. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

The System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The <unistd.h> header is added to the SYNOPSIS section. 

The type of argument src is changed from char’ 1 ' to const void 51 ', dest is changed from char 5 '' to 
void*, and nbytes is changed from int to ssize_t- 

The DESCRIPTION is changed as follows: 

• States explicitly that copying between overlapping objects results in undefined behavior. 

• Takes account of the type change to nbyte; that is, previously it was defined as int and could 
be positive or negative, whereas now it is defined as an unsigned type. 

• A statement about overlapping objects is added. 

The APPLICATION USAGE section is removed. 
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41362 NAME 

41363 swapcontext — swap user context 

41364 SYNOPSIS 

41365 xsi #include <ucontext.h> 

41366 int swapcontext (ucontext_t *oucp r const ucontext_t *ucp) ; 

41367 

41368 DESCRIPTION 

41369 Refer to makecontext(). 
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41370 NAME 

41371 swprintf — print formatted wide-character output 

41372 SYNOPSIS 

41373 #include <stdio.h> 

41374 #include <wchar.h> 

41375 int swprintf (wchar_t *s, size_t n, const wchar 

41376 DESCRIPTION 

41377 Refer to fivprin tf (). 


* format, . . . ); 
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41378 NAME 

41379 swscanf — convert formatted wide-character input 

41380 SYNOPSIS 

41381 #include <stdio.h> 

41382 #include <wchar.h> 

41383 int swscanf (const wchar_t *s, const wchar 

41384 DESCRIPTION 

41385 Refer to fwscanf (). 


* format, ... ); 
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41386 NAME 

41387 symlink — make symbolic link to a file I 

41388 SYNOPSIS 

41389 #include <unistd.h> | 

41390 int symlink (const char *pathl, const char *path2) ; 

41391 DESCRIPTION I 

41392 The symlink( ) function shall create a symbolic link called patli2 that contains the string pointed I 

41393 to by pathl ( path2 is the name of the symbolic link created, pathl is the string contained in the I 

41394 symbolic link). I 

41395 The string pointed to by path 1 shall be treated only as a character string and shall not be I 

41396 validated as a path name. I 

41397 If the symlink( ) function is unsuccessful, any file named by path! shall be unaffected. I 

41398 RETURN VALUE 

41399 Upon successful completion, symlink ( ) shall return 0; otherwise, it shall return -1 and set errno to 

41400 indicate the error. 


41401 ERRORS 

41402 The symlink () function shall fail if: 


41403 

41404 

41405 


[EACCES] Write permission is denied in the directory where the symbolic link is being 

created, or search permission is denied for a component of the path prefix of 
path!. 


41406 

41407 

41408 

41409 


[EEXIST] The pathl argument names an existing file or symbolic link. 

[EIO] An I/O error occurs while reading from or writing to the file system. 

[ELOOP] A loop exists in symbolic links encountered during resolution of the pathl I 

argument. I 


41410 

41411 

41412 

41413 

41414 


[ENAMETOOLONG] 

The length of the pathl argument exceeds |PATH_MAX}, or a path name 
component is longer than {NAME_MAX} while _POSIX_NO_TRUNC is in I 
effect, or the length of the string pointed to by pname exceeded I 
|SYMLINK_MAX}. I 


41415 [ENOENT] A component of pathl does not name an existing file or pathl is an empty 

41416 string. 


41417 

41418 

41419 

41420 

41421 


[ENOSPC] The directory in which the entry for the new symbolic link is being placed 

cannot be extended because no space is left on the file system containing the 
directory, or the new symbolic link cannot be created because no space is left 
on the file system which shall contain the link, or the file system is out of file- 
allocation resources. 


41422 [ENOTDIR] A component of the path prefix of pathl is not a directory. 

41423 [EROFS] The new symbolic link would reside on a read-only file system. 

41424 The symlink () function may fail if: 

41425 [ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during I 

41426 resolution of the pathl argument. I 

41427 [ENAMETOOLONG] 

41428 As a result of encountering a symbolic link in resolution of the pathl I 
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41429 

41430 

41431 

41432 EXAMPLES 

41433 None 

41434 APPLICATION USAGE 

41435 Like a hard link, a symbolic link allows a file to have multiple logical names. The presence of a 

41436 hard link guarantees the existence of a file, even after the original name has been removed. A 

41437 symbolic link provides no such assurance; in fact, the file named by the pathl argument need not 

41438 exist when the link is created. A symbolic link can cross file system boundaries. 

41439 Normal permission checks are made on each component of the symbolic link path name during 

41440 its resolution. 

41441 RATIONALE 

41442 Since IEEE Std. 1003.1-200x does not require any association of file times with symbolic links, I 

41443 there is no requirement that file times be updated by symlink (). I 

41444 FUTURE DIRECTIONS 

41445 None. 

41446 SEE ALSO 

41447 lchozvn(), link(), Istat (), open(), readlink{), unlink(), the System Interface Definitions volume of I 

41448 IEEE Std. 1003.1-200x, <unistd.h> 

41449 CHANGE HISTORY 

41450 First released in Issue 4, Version 2. 

41451 Issue 5 

41452 Moved from X/OPEN UNIX extension to BASE. 

41453 Issue 6 

41454 The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

41455 • The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 

41456 This is since behavior may vary from one file system to another. 

41457 The following changes were made to align with the IEEE P1003.1a draft standard: I 

41458 • The DESCRIPTION text is updated. 

41459 • The [ELOOP] optional error condition is added. I 


argument, the length of the substituted path name string exceeded I 
|PATH_MAX} bytes (including the terminating null byte), or the length of the I 
string pointed to by pathl exceeded jSYMLINK_MAX). I 
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41460 NAME 

41461 sync — schedule file system updates 

41462 SYNOPSIS 

41463 xsi tinclude <unistd.h> 

41464 void sync (void) ; 

41465 

41466 DESCRIPTION 

41467 The sync() function shall cause all information in memory that updates file systems to be 

41468 scheduled for writing out to all file systems. 

41469 The writing, although scheduled, is not necessarily complete upon return from sync (). 

41470 RETURN VALUE 

41471 The sync( ) function shall return no value. 

41472 ERRORS 

41473 No errors are defined. 

41474 EXAMPLES 

41475 None. 

41476 APPLICATION USAGE 

41477 None. 

41478 RATIONALE 

41479 None. 

41480 FUTURE DIRECTIONS 

41481 None. 

41482 SEE ALSO 

41483 fsync{ ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

41484 CHANGE HISTORY 

41485 First released in Issue 4, Version 2. 

41486 Issue 5 

41487 Moved from X/OPEN UNIX extension to BASE. 
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41488 NAME 

41489 sysconf — get configurable system variables 

41490 SYNOPSIS 

41491 #include <unistd.h> 

41492 long int sysconf (int name) ; 

41493 DESCRIPTION 

41494 The sysconf () function provides a method for the application to determine the current value of a 

41495 configurable system limit or option (variable). Support for some system variables is dependent I 

41496 on implementation options (as indicated by the margin codes in the following table). Where an I 

41497 implementation option is not supported, the variable need not be supported. I 

41498 The name argument represents the system variable to be queried. The following table lists the 

41499 minimal set of system variables from <limits.h> or <unistd.h> that can be returned by sysconf (), 

41500 and the symbolic constants, defined in <unistd.h> that are the corresponding values used for I 

41501 name. Support for some configuration variables is dependent on implementation options (see I 

41502 shading and margin codes in the table below). Where an implementation option is not I 


41503 

41504 

supported, the variable need not be supported. 


41505 

Variable 

Value of Name 

41506 AIO 

j AIO_LISTIO_M AX} 

_SC_AIO_LISTIO_MAX 

41507 

|AIO_MAX} 

_SC_AIO_MAX 

41508 

{AIO_PRIO_DELTA_M AX} 

_SC_AIO_PRIO_DELTA_MAX 

41509 

|ARG_MAX} 

_SC_ARG_MAX 

41510 XSI 

|ATEXIT_MAX} 

_SC_ATEXIT_MAX 

41511 

|BC_BASE_MAX} 

_SC_BC_BASE_MAX 

41512 

j BC_DIM_MAX} 

_SC_BC_DIM_MAX 

41513 

|BC_SCALE_MAX} 

_SC_BC_SCALE_MAX 

41514 

|BC_STRING_MAX} 

_SC_BC_STRING_MAX 

41515 

|CHILD_MAX} 

_SC_C HILD_M AX 

41516 

Clock ticks/second 

_SC_CLK_TCK 

41517 

|COLL_WEIGHTS_MAX} 

_SC_COLL_WEIGHTS_MAX 

41518 XSI 

|DELAYTIMER_MAX} 

_SC_DELAYTIMER_MAX 

41519 

j EXPR_NEST_M AX} 

_SC_EXPR_NEST_MAX 

41520 XSI 

|IOV_MAX} 

_SC_IOV_MAX 

41521 

|LINE_MAX} 

_SC_LINE_MAX 

41522 

j LOGIN_N AME_M AX) 

_SC_LOGIN_NAME_MAX 

41523 

|NGROUPS_MAX} 

_SC_NGROUPS_MAX 

41524 TSF 

41525 

Maximum size of getgrgid_r () and 
getgrnam_r () data buffers 

_SC_GET GR_R_SIZE_MAX 

41526 

41527 

Maximum size of getpivnid_r () and 
getpzvnam_r () data buffers 

_SC_GETPW_R_SIZE_MAX 

41528 MSG 

|MQ_OPEN_MAX} 

_SC_MQ_OPEN_MAX 

41529 

{MQ_PRIO_MAX} 

_SC_MQ_PRIO_MAX 

41530 

|OPEN_MAX} 

_SC_OPEN_MAX 

41531 ADV 

_POSIX_ADVISORY_INFO 

_SC_ADVISORY_INFO 

41532 BAR 

_POSIX_BARRIERS 

_SC_BARRIERS 

41533 AIO 

_POSIX_ASYNCHRONOUS_IO 

_SC_ASYNCHRONOUS_IO 
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41534 


41535 

Variable 

Value of Name 

41536 

_POSIX_BASE 

_SC_BASE 

41537 

_POSIX_C_LANG_SUPPORT 

_SC_C_LANG_SUPPORT 

41538 

_POSIX_C_LANG_SUPPORT_R 

_SC_C_LANG_SUPPORT_R 

41539 CS 

_POSIX_CLOCK_SELECTION 

_SC_CLOCK_SELECTION 

41540 CPT 

_POSIX_CPUTIME 

_SC_CPUTIME 

41541 

_POSIX_DEVICE_IO 

_SC_DEVICE_IO 

41542 

_POSIX_DEVICE_SPECIFIC 

_SC_DEVICE_SPECIFIC 

41543 

_POSIX_DEVICE_SPECIFIC_R 

_SC_DEVICE_SPECIFIC_R 

41544 

_POSIX_FD_MGMT 

_SC_FD_MGMT 

41545 

_POSIX_FIFO 

_SC_FIFO 

41546 

_POSIX_FILE_ATTRIBUTES 

_SC_FILE_ATTRIBUTES 

41547 

_POSIX_FILE_LOCKING 

_SC_FILE_LOCKING 

41548 

_POSIX_FILE_S Y STEM 

_SC_FILE_S Y STEM 

41549 FSC 

_POSIX_FSYNC 

_SC_FSYNC 

41550 

_POSIXJOB_CONTROL 

_SCJOB_CONTROL 

41551 MF 

41552 

_POSIX_MAPPED_FILES 

_SC_MAPPED_FILES 

_SC_MAPPED_FILES 

41553 ML 

_POSIX_MEMLOCK 

_SC_MEMLOCK 

41554 MLR 

_POSIX_MEMLOCK_RANGE 

_SC_MEMLOCK_RANGE 

41555 MPR 

_POSIX_MEMORY_PROTECTION 

_SC_MEMORY_PROTECTION 

41556 MSG 

_POSIX_MESSAGE_PASSING 

_SC_MESSAGE_PASSING 

41557 MON 

_POSIX_MONOTONIC_CLOCK 

_SC_MONOTONIC_CLOCK 

41558 

_POSIX_MULTIPLE_PROCESS 

_SC_MULTIPLE_PROCESS 

41559 

_POSIX_NETWORKING 

_SC_NETWORKING 

41560 

_POSIX_PIPE 

_SC_PIPE 

41561 PIO 

_POSIX_PRIORITIZED_IO 

_SC_PRIORITIZED_IO 

41562 PS 

_POSIX_PRIORITY_SCHEDULING 

_SC_PRIORITY_SCHEDULING 

41563 RWL 

_POSIX_READER_WRITER_LOCKS 

_SC_READER_WRITER_LOCKS 

41564 RTS 

_posix_realtime_signals 

_sc_realtime_signals 

41565 

_POSIX_REGEXP 

_SC_REGEXP 

41566 

_POSIX_SAVED_IDS 

_SC_SAVED_IDS 

41567 SEM 

_POSIX_SEMAPHORES 

_SC_SEMAPHORES 

41568 SHM 

_POSIX_SHARED_MEMORY_OBJECTS 

_SC_SHARED_MEMORY_OBJECTS 

41569 

_POSIX_SHELL 

_SC_SHELL 

41570 

_POSIX_SIGNALS 

_sc_signals 

41571 

_POSIX_SINGLE_PROCESS 

_SC_SINGLE_PROCESS 

41572 SPN 

_POSIX_SPAWN 

_SC_SPAWN 

41573 SPI 

_POSIX_SPIN_LOCKS 

_SC_SPIN_LOCKS 

41574 SS 

_POSIX_SPORADIC_SERVER 

_SC_SPORADIC_SERVER 

41575 SIO 

_POSIX_SYNCHRONIZED_IO 

_SC_SYNCHRONIZED_IO 

41576 

_POSIX_S Y STEM_D ATAB ASE 

_SC_S Y STEM_D ATAB ASE 

41577 

_POSIX_S Y STEM_D ATAB ASE_R 

_SC_S Y STEM_D ATAB ASE_R 
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41579 

Variable 

Value of Name 

41580 TSA 

_POSIX_THREAD_ATTR_STACKADDR 

_SC_THREAD_ATTR_STACKADDR 

41581 TSS 

_POSIX_THREAD_ATTR_STACKSIZE 

_SC_THREAD_ATTR_STACKSIZE 

41582 TCT 

_POSIX_THREAD_CPUTIME 

_SC_THREAD_CPUTIME 

41583 TPI 

_POSIX_THREAD_PRIO_INHERIT 

_SC_THREAD_PRIO_INHERIT 

41584 TPP 

_POSIX_THREAD_PRIO_PROTECT 

_SC_THREAD_PRIO_PROTECT 

41585 TPS 

_POSIX_THREAD_PRIORITY_SCHEDULING 

_SC_THREAD_PRIORITY_SCHEDULING 

41586 TSH 

_POSIX_THREAD_PROCESS_SHARED 

_SC_THREAD_PROCESS_SHARED 

41587 TSF 

_POSIX_THREAD_SAFE_FUNCTIONS 

_SC_THREAD_SAFE_FUNCTIONS 

41588 TSP 

_POSIX_THREAD_SPORADIC_SERVER 

_SC_THREAD_SPORADIC_SERVER 

41589 THR 

_POSIX_THREADS 

_SC_THREADS 

41590 TMO 

_POSIX_TIMEOUTS 

_SC_TIMEOUTS 

41591 TMR 

_POSIX_TIMERS 

_SC_TIMERS 

41592 TYM 

_POSIX_TYPED_MEMORY_OBJECTS 

_SC_TYPED_MEMORY_OBJECTS 

41593 

_POSIX_USER_GROUPS 

_SC_USER_GROUPS 

41594 

_POSIX_USER_GROUPS_R 

_SC_USER_GROUPS_R 

41595 

_POSIX_VERSION 

_SC_VERSION 

41596 

_POSIX2_C_BIND 

_SC_2_C_BIND 

41597 

_POSIX2_C_DEV 

_SC_2_C_DEV 

41598 

_POSIX2_C_VERSION 

_SC_2_C_VERSION 

41599 

_POSIX2_C H AR_TERM 

_SC_2_CHAR_TERM 

41600 

_POSIX2_FORT_DEV 

_SC_2_FORT_DEV 

41601 

_POSIX2_FORT_RUN 

_SC_2_FORT_RUN 

41602 

_POSIX2_LOCALEDEF 

_SC_2_LOC ALEDEF 

41603 BE 

_POSIX2_PBS 

_SC_2_PBS 

41604 

_POSIX2_PBS_ACCOUNTING 

_SC_2_PBS_ACCOUNTING 

41605 

_POSIX2_PBS_LOCATE 

_SC_2_PBS_LOCATE 

41606 

_POSIX2_PBS_MESSAGE 

_SC_2_PBS_MESSAGE 

41607 

_POSIX2_PBS_TRACK 

_SC_2_PBS_TRACK 

41608 

_POSIX2_SW_DEV 

_SC_2_SW_DEV 

41609 

_POSIX2_UPE 

_SC_2_UPE 

41610 

_POSIX2_VERSION 

_SC_2_VERSION 

41611 

_REGEX_VERSION 

_SC_REGEX_VERSION 

41612 XSI 

|PAGE_SIZE} 

_SC_PAGE_SIZE 

41613 

jPAGESIZE) 

_SC_PAGESIZE 

41614 THR 

{PTHREAD_DESTRUCTOR_ITERATIONS} 

_SC_THREAD_DESTRUCTOR_ITERATIONS 

41615 

j PTHRE AD_KE Y S_M AX} 

_SC_THRE AD_KE Y S_M AX 

41616 

|PTHREAD_STACK_MIN} 

_SC_THREAD_STACK_MIN 

41617 

{PTHREAD_THREADS_MAX} 

_SC_THREAD_THREADS_MAX 

41618 

j RE_DUP_M AX) 

_SC_RE_DUP_MAX 

41619 RTS 

|RTSIG_MAX} 

_SC_RTSIG_MAX 

41620 SEM 

|SEM_NSEMS_MAX} 

_SC_SEM_NSEMS_MAX 

41621 

|SEM_VALUE_MAX} 

_SC_SEM_VALUE_MAX 

41622 RTS 

{SIGQUEUE_MAX} 

_sc_sigqueue_max 

41623 

j STRE AM_MAX} 

_SG_S 1 RE AM_M AX 

41624 

|SYMLOOP_MAX} 

_SC_SYMLOOP_MAX 

41625 TMR 

|TIMER_MAX) 

_SC_TIMER_MAX 

41626 

j TT Y_N AME_M AX} 

_SC_TTY_NAME_MAX 
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|TZNAME_MAX} 


SC_TZNAME_MAX 
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41629 

Variable 

Value of Name 

41630 

|TZNAME_MAX} 

_SC_TZNAME_MAX 

41631 XSI 

_XBS5_ILP32_OFF32 

_SC_XBS5_ILP32_OFF32 

41632 

_XBS5_ILP32_OFFBIG 

_SC_XBS5_ILP32_OFFBIG 

41633 

_XBS5_LP64_OFF64 

_SC_XBS5_LP64_OFF64 

41634 

_XBS5_LPBIG_OFFBIG 

_SC_XBS5_LPBIG_OFFBIG 

41635 

_XOPEN_CRYPT 

_SC_XOPEN_CRYPT 

41636 

_XOPEN_ENH_I18N 

_SC_XOPEN_ENH_I18N 

41637 

_XOPEN_LEGACY 

_SC_XOPEN_LEGACY 

41638 

_XOPEN_REALTIME 

_SC_XOPEN_REALTIME 

41639 

_XOPEN_REALTIME_THREADS 

_SC_XOPEN_REALTIME_THREADS 

41640 

_XOPEN_SHM 

_SC_XOPEN_SHM 

41641 

_XOPEN_UNIX 

_SC_XOPEN_UNIX 

41642 

_XOPEN_VERSION 

_SC_XOPEN_VERSION 

41643 

_XOPEN_XCU_VERSION 

_SC_XOPEN_XCU_VERSION 


41644 RETURN VALUE I 

41645 If name is an invalid value, sysconf( ) shall return -1 and set errno to indicate the error. If the 

41646 variable corresponding to name has no limit, sysconf( ) shall return -1 without changing the value I 

41647 of errno. Note that indefinite limits do not imply infinite limits; see <limits.h>. I 

41648 Otherwise, sysconf( ) shall return the current variable value on the system. The value returned 

41649 shall not be more restrictive than the corresponding value described to the application when it 

41650 was compiled with the implementation's <limits.h> or <unistd.h>. The shall does not change 

41651 during the lifetime of the calling process. 

41652 ERRORS 

41653 The sysconf( ) function shall fail if: 

41654 [EINVAL] The value of the name argument is invalid. 

41655 EXAMPLES 

41656 None. 

41657 APPLICATION USAGE 

41658 As -1 is a permissible return value in a successful situation, an application wishing to check for 

41659 error situations should set errno to 0, then call sysconf( ), and, if it returns -1, check to see if errno 

41660 is non-zero. 

41661 If the value of sysco ;i/(_SC_2_ V ERSI ON) is not equal to the value of the _POSIX2_VERSION 

41662 symbolic constant, the utilities available via system () or popen () might not behave as described in 

41663 the Commands and Utilities volume of IEEE Std. 1003.1-200x. This would mean that the 

41664 application is not running in an environment that conforms to the Commands and Utilities 

41665 volume of IEEE Std. 1003.1-200x. Some applications might be able to deal with this, others might 

41666 not. However, the functions defined in this volume of IEEE Std. 1003.1-200x continue to operate 

41667 as specified, even if: sysen;i/(_SC_2_VERSI(3N) reports that the utilities no longer perform as 

41668 specified. 

41669 RATIONALE 

41670 This functionality was added in response to requirements of application developers and of 

41671 system vendors who deal with many international system configurations. It is closely related to 

41672 pathconf( ) and fpathconf( ). 

41673 Although a portable application can run on all systems by never demanding more resources 

41674 than the minimum values published in this volume of IEEE Std. 1003.1-200x, it is useful for that 

41675 application to be able to use the actual value for the quantity of a resource available on any 
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41676 given system. To do this, the application makes use of the value of a symbolic constant in 

41677 <limits.h> or <unistd.h>. 

41678 However, once compiled, the application must still be able to cope if the amount of resource 

41679 available is increased. To that end, an application may need a means of determining the quantity 

41680 of a resource, or the presence of an option, at execution time. 

41681 Two examples are offered: 

41682 1. Applications may wish to act differently on systems with or without job control. 

41683 Applications vendors who wish to distribute only a single binary package to all instances 

41684 of a computer architecture would be forced to assume job control is never available if it 

41685 were to rely solely on the <unistd.h> value published in this volume of 

41686 IEEE Std. 1003.1-200x. 

41687 2. International applications vendors occasionally require knowledge of the number of clock 

41688 ticks per second. Without these facilities, they would be required to either distribute their 

41689 applications partially in source form or to have 50Hz and 60Hz versions for the various 

41690 countries in which they operate. 

41691 It is the knowledge that many applications are actually distributed widely in executable form 

41692 that leads to this facility. If limited to the most restrictive values in the headers, such 

41693 applications would have to be prepared to accept the most limited environments offered by the 

41694 smallest microcomputers. Although this is entirely portable, there was a consensus that they 

41695 should be able to take advantage of the facilities offered by large systems, without the 

41696 restrictions associated with source and object distributions. 

41697 During the discussions of this feature, it was pointed out that it is almost always possible for an 

41698 application to discern what a value might be at runtime by suitably testing the various functions I 

41699 themselves. And, in any event, it could always be written to adequately deal with error returns I 

41700 from the various functions. In the end, it was felt that this imposed an unreasonable level of 

41701 complication and sophistication on the application writer. 

41702 This runtime facility is not meant to provide ever-changing values that applications have to I 

41703 check multiple times. The values are seen as changing no more frequently than once per system 

41704 initialization, such as by a system administrator or operator with an automatic configuration 

41705 program. This volume of IEEE Std. 1003.1-200x specifies that they shall not change within the 

41706 lifetime of the process. 

41707 Some values apply to the system overall and others vary at the file system or directory level. The 

41708 latter are described in pathconf( ). 

41709 Note that all values returned must be expressible as integers. String values were considered, but 

41710 the additional flexibility of this approach was rejected due to its added complexity of 

41711 implementation and use. 

41712 Some values, such as |PATH_MAX}, are sometimes so large that they must not be used to, say, 

41713 allocate arrays. The sysconfO function returns a negative value to show that this symbolic 

41714 constant is not even defined in this case. I 

41715 Similar to pathconf( ), this permits the implementation not to have a limit. When one resource is I 

41716 infinite, returning an error indicating that some other resource limit has been reached is I 

41717 conforming behavior. I 

41718 FUTURE DIRECTIONS 

41719 None. 
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41720 

41721 

41722 

41723 

41724 

41725 

41726 

41727 

41728 

41729 

41730 

41731 

41732 

41733 

41734 

41735 

41736 

41737 

41738 

41739 

41740 

41741 

41742 

41743 

41744 

41745 

41746 

41747 

41748 

41749 

41750 

41751 

41752 

41753 

41754 

41755 

41756 

41757 

41758 

41759 

41760 


SEE ALSO 

confstr(), pathconfO, the System Interface Definitions volume of IEEEStd. 1003.l-200x, 
<limits.h>, <unistd.h>, the Commands and Utilities volume of IEEE Std. 1003.1-200x, getconf 

CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the POSIX.1-1988 standard. 


Issue 4 

The type of the function return value is expanded to long int. 

_XOPEN_VERSION is added to the table of configurable system limits; this should have been 
included in Issue 3. 

The following variables are added to the table of configurable system limits in the 
DESCRIPTION and marked as extensions: 

_XOPEN_CRYPT 

_XOPEN_ENH_I18N 

_XOPEN_SHM 

_XOPEN_UNIX 

In the RETURN VALUE section the header <time.h> is given as an alternative to <limits.h> and 
<unistd.h>. 

The second paragraph is added to the APPLICATION USAGE section. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The variables {STREAM_MAX} and |TZNAME_MAX} are added to the table of variables in 
the DESCRIPTION. 

The following change is incorporated for alignment with the ISO POSIX-2 standard: 

• The following variables are added to the table of configurable system limits in the 
DESCRIPTION: 

|BC_BASE_MAX} 
j BC_DIM_M AX} 

| BC_SC ALE_M AX} 

|BC_STRING_MAX} 

{COLL_WEIGHTS_MAX} 

{EXPR_NEST_MAX} 

|LINE_MAX} 

Issue 4, Version 2 

For X/OPEN UNIX conformance, the {ATEXIT_MAX}, {IOV_MAX}, {PAGESIZE}, {PAGE_SIZE}, 
and _XOPEN_UNIX variables are added to the list of configurable system values that can be 
determined by calling sysconf (). 

Issue 5 

The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 
Threads Extension. 

The _XBS_ variables and name values are added to the table of system variables in the 
DESCRIPTION. These are all marked EX. 
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POSIX2_C_BIND _POSIX2_SW_DEV 

POSIX2_C_DEV _POSIX2_VERSION 

POSIX2_C_VERSION |RE_DUP_MAX} 

POSIX2_C H AR_TERM 

POSIX2_FORT_DEV 

POSIX2_FORT_RUN 

POSIX2_LOCALEDEF 
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41761 

41762 

41763 

41764 

41765 

41766 

41767 

41768 

41769 

41770 

41771 

41772 

41773 

41774 

41775 

41776 

41777 

41778 

41779 

41780 

41781 

41782 

41783 

41784 

41785 

41786 

41787 

41788 

41789 

41790 

41791 

41792 


Issue 6 

The symbol CLK_TCK is obsolescent and removed. It is replaced with the phrase "clock ticks 
per second". 

The symbol jPASS_MAX} is removed. 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• Table entries added for the following variables: _SC_REGEXP, _SC_SHELL, 
_SC_REGEX_VERSION,_SC_SYMLOOP_MAX. 

The following sysconfO variables and their associated names are added for alignment with 
IEEE Std. 1003.1d-1999: 

_POSIX_ADVISORY_INFO 

_POSIX_CPUTIME 

_POSIX_SPAWN 

_POSIX_SPORADIC_SERVER 

_POSIX_THREAD_CPUTIME 

_POSIX_THREAD_SPORADIC_SERVER 

_POSIX_TIMEOUTS 

The following changes are made to the DESCRIPTION for alignment with 
IEEE Std. 1003.1j-2000: 

• A statement expressing the dependency of support for some system variables on 
implementation options is added. 

• The following system variables are added: 

_POSIX_BARRIERS 

_POSIX_CLOCK_SELECTION 

_POSIX_MONOTONIC_CLOCK 

_POSIX_READER_WRITER_LOCKS 

_POSIX_SPIN_LOCKS 

_POSIX_TYPED_MEMORY_OBJECTS 

_POSIX2_PBS 

_POSIX2_PBS_ACCOUNTING 
_POSIX2_PBS_LOC ATE 
_POSIX2_PBS_MESSAGE 
_POSIX2_PBS_TRACK 


System Interfaces, Issue 6 


1375 




syslogO 


System Interfaces 


41793 NAME 

41794 syslog — log a message 

41795 SYNOPSIS 

41796 xsi tinclude <syslog.h> 

41797 void syslog (int priority, const char *message, 

41798 

41799 DESCRIPTION 

41800 Refer to closelog(). 


/* argument */); 
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41801 NAME 

41802 system — issue a command 

41803 SYNOPSIS 

41804 #include <stdlib.h> 

41805 int system (const char * command) ; 

41806 DESCRIPTION 

41807 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

41808 conflict between the requirements described here and the ISO C standard is unintentional. This I 

41809 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

41810 The system() function passes the string pointed to by command to the host environment to be 

41811 executed by a command processor in an implementation-dependent manner. The environment I 

41812 of the executed command shall be as if a child process were created using the fork () function, I 

41813 and the child process invoked a command interpreter using the execl () function. I 

41814 cx If the implementation supports the Commands and Utilities volume of IEEE Std. 1003.1-200x I 

41815 commands, the environment of the executed command shall be as if a child process were created 

41816 using fork( ), and the child process invoked the sh utility using execl () as follows: 

41817 execl (<shell path>, "sh", "-c", command, (char *)0); 

41818 where <shell path> is an unspecified path name for the sh utility. 

41819 The system () function ignores the SIGINT and SIGQUIT signals, and blocks the SIGCHLD 

41820 signal, while waiting for the command to terminate. If this might cause the application to miss a 

41821 signal that would have killed it, then the application should examine the return value from 

41822 s ystem( ) and take whatever action is appropriate to the application if the command terminated 

41823 due to receipt of a signal. 

41824 The system () function shall not affect the termination status of any child of the calling processes 

41825 other than the process or processes it itself creates. 

41826 The system () function shall not return until the child process has terminated. 

41827 RETURN VALUE 

41828 If command is a null pointer, system () shall return non-zero to indicate that a command processor I 

41829 cx is available, or zero if none is available. If the implementation supports the utilities defined in I 

41830 the Commands and Utilities volume of IEEE Std. 1003.1-200x, system( ) shall always return non- I 

41831 zero when command is NULL. I 

41832 cx If command is not a null pointer, system() shall return the termination status of the command 

41833 language interpreter in the format specified by zvaitpid(). If the implementation supports the I 

41834 utilities defined in the Commands and Utilities volume of IEEE Std. 1003.1-200x, the termination I 

41835 status shall be as defined for the sh utility; otherwise, the termination status is unspecified. If I 

41836 some error prevents the command language interpreter from executing after the child process is I 

41837 created, the return value from system() shall be as if the command language interpreter had I 

41838 terminated using exit(127) or _exit(\27). If a child process cannot be created, or if the 

41839 termination status for the command language interpreter cannot be obtained, system() shall 

41840 return -1 and set errno to indicate the error. 

41841 ERRORS 

41842 cx The system( ) function may set errno values as described by fork (). 

41843 In addition, system( ) may fail if: 

41844 cx [ECHILD] The status of the child process created by system () is no longer available. 
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41845 EXAMPLES 

41846 None. 

41847 APPLICATION USAGE 

41848 If the return value of system() is not -1, its value can be decoded through the use of the macros 

41849 described in <sys/wait.h>. For convenience, these macros are also provided in <stdlib.h>. 

41850 To determine whether or not the environment specified in the Commands and Utilities volume 

41851 of IEEE Std. 1003.1-200x is present, use sysco ;i/(_SC_2_VERSION). 

41852 Note that, while system () must ignore SIGINT and SIGQUIT and block SIGCHLD while waiting 

41853 for the child to terminate, the handling of signals in the executed command is as specified by 

41854 fork() and exec. For example, if SIGINT is being caught or is set to SIG_DFL when system () is 

41855 called, then the child is started with SIGINT handling set to SIG_DFL. 

41856 Ignoring SIGINT and SIGQUIT in the parent process prevents coordination problems (two 

41857 processes reading from the same terminal, for example) when the executed command ignores or 

41858 catches one of the signals. It is also usually the correct action when the user has given a 

41859 command to the application to be executed synchronously (as in the ' !' command in many 

41860 interactive applications). In either case, the signal should be delivered only to the child process, 

41861 not to the application itself. There is one situation where ignoring the signals might have less 

41862 than the desired effect. This is when the application uses system( ) to perform some task invisible 

41863 to the user. If the user typed the interrupt character (" ~C", for example) while system () is being 

41864 used in this way, one would expect the application to be killed, but only the executed command 

41865 is killed. Applications that use system( ) in this way should carefully check the return status from 

41866 system() to see if the executed command was successful, and should take appropriate action 

41867 when the command fails. 

41868 Blocking SIGCHLD while waiting for the child to terminate prevents the application from 

41869 catching the signal and obtaining status from system! )'s child process before system () can get the 

41870 status itself. 

41871 The context in which the utility is ultimately executed may differ from that in which system() 

41872 was called. For example, file descriptors that have the FD_CLOEXEC flag set are closed, and the 

41873 process ID and parent process ID are different. Also, if the executed utility changes its 

41874 environment variables or its current working directory, that change is not reflected in the caller's 

41875 context. 

41876 There is no defined way for an application to find the specific path for the shell. However, 

41877 confstr( ) can provide a value for PATH that is guaranteed to find the sh utility. 

41878 RATIONALE 

41879 The system() function should not be used by programs that have set user (or group) ID 

41880 privileges. The fork( ) and exec family of functions (except execlp( ) and execvp( )), should be used 

41881 instead. This prevents any unforeseen manipulation of the environment of the user that could 

41882 cause execution of commands not anticipated by the calling program. 

41883 There are three levels of specification for the system () function. The ISOC standard gives the 

41884 most basic. It requires that the function exists, and defines a way for an application to query 

41885 whether a command language interpreter exists. It says nothing about the command language or 

41886 the environment in which the command is interpreted. 

41887 IEEE Std. 1003.l-200x places additional restrictions on system (). It requires that if there is a 

41888 command language interpreter, the environment must be as specified by fork () and exec. This 

41889 ensures, for example, that close-on -exec works, that file locks are not inherited, and that the 

41890 process ID is different. It also specifies the return value from system () when the command line 

41891 can be run, thus giving the application some information about the command's completion 
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41892 

41893 

41894 

41895 

41896 

41897 

41898 

41899 

41900 

41901 

41902 

41903 

41904 

41905 

41906 

41907 

41908 

41909 

41910 

41911 

41912 

41913 

41914 

41915 

41916 

41917 

41918 

41919 

41920 

41921 

41922 

41923 

41924 

41925 

41926 

41927 

41928 

41929 

41930 

41931 

41932 

41933 

41934 

41935 

41936 

41937 

41938 


status IEEE Std. 1003.1-200x in its base definition still says nothing about the interpretation of 
the command. 

Finally, IEEE Std. 1003.1-200x requires the command to be interpreted as in the shell command 
language defined in the Commands and Utilities volume of IEEE Std. 1003.1-200x. 

Note that, system (NULL) is required to return non-zero, indicating that there is a command 
language interpreter. At first glance, this would seem to conflict with the ISO C standard which 
allows system (NULL) to return zero. There is no conflict, however. A system have a command 
language interpreter, and is non-conforming if none is present. It is therefore permissible for the 
system () function on such a system to implement the behavior specified by the ISO C standard 
as long as it is understood that the implementation does not conform to IEEE Std. 1003.1-200x if 
system (NULL) returns zero. 

It was explicitly decided that when command is NULL, system () should not be required to check 
to make sure that the command language interpreter actually exists with the correct mode, that 
there are enough processes to execute it, and so on. The call system (NULL) could, theoretically, 
check for such problems as too many existing child processes, and return zero. However, it 
would be inappropriate to return zero due to such a (presumably) transient condition. If some 
condition exists that is not under the control of this application and that would cause any 
system () call to fail, that system has been rendered non-conforming. 

Early drafts required, or allowed, system( ) to return with errno set to [EINTR] if it was 
interrupted with a signal. This error return was removed, and a requirement that system () not 
return until the child has terminated was added. This means that if a zvaitpid () call in system () 
exits with errno set to [EINTR], system{ ) must re-issue the zvaitpid (). This change was made for 
two reasons: 

1. There is no way for an application to clean up if system () returns [EINTR], short of calling 
zvait(), and that could have the undesirable effect of returning the status of children other 
than the one started by system ( ). 

2. While it might require a change in some historical implementations, those 
implementations already have to be changed because they use ivait() instead of zvaitpid (). 

Note that if the application is catching SIGCHLD signals, it will receive such a signal before a 
successful system( ) call returns. 

To conform to IEEE Std. 1003.l-200x, system() must use zvaitpid (), or some similar function, 
instead of zvait( ). 

The following code sample illustrates how system () might be implemented on an 
implementation conforming to IEEE Std. 1003.1-200x. 

#include <signal.h> 

int system(const char *cmd) 

{ 

int stat; 
pid_t pid; 

struct sigaction sa, savintr, savequit; 
sigset_t saveblock; 
if (cmd == NULL) 
return(1); 

sa.sa_handler = SIG_IGN; 
sigemptyset(&sa.sa_mask) ; 
sa.sa_flags = 0; 
sigemptyset(Ssavintr.sa_mask) ; 
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41939 

41940 

41941 

41942 

41943 

41944 

41945 

41946 

41947 

41948 

41949 

41950 

41951 

41952 

41953 

41954 

41955 

41956 

41957 

41958 

41959 

41960 

41961 

41962 

41963 

41964 

41965 


sigemptyset(&savequit.sa_mask) ; 
sigaction(SIGINT, Ssa, Ssavintr) ; 
sigaction(SIGQUIT, Ssa, Ssavequit); 
sigaddset(Ssa.sa_mask, SIGCHLD) ; 

sigprocmask(SIG_BLOCK, Ssa.sa_mask, Ssaveblock); 
if ( (pid = fork()) == 0) { 

sigaction(SIGINT, Ssavintr, (struct sigaction *)0); 
sigaction(SIGQUIT, Ssavequit, (struct sigaction *)0); 
sigprocmask(SIG_SETMASK, Ssaveblock, (sigset_t *)0); 
execl("/bin/sh", "sh", "-c", cmd, (char *)0); 

_exit (127); 

} 

if (pid == -1) { 

stat = -1; /* errno comes from fork() */ 

} else { 

while (waitpid(pid, &stat, 0) == -1) { 

if (errno != EINTR){ 
stat = -1; 
break; 


sigaction(SIGINT, Ssavintr, (struct sigaction *)0); 
sigaction(SIGQUIT, Ssavequit, (struct sigaction *)0); 
sigprocmask(SIG_SETMASK, Ssaveblock, (sigset_t *)0); 
return(stat); 


41966 Note that, while a particular implementation of system{ ) (such as the one above) can assume a 

41967 particular path for the shell, such a path is not necessarily valid on another system. The above 

41968 example is not portable, and is not intended to be. 

41969 One reviewer suggested that an implementation of system () might want to use an environment 

41970 variable such as SHELL to determine which command interpreter to use. The supposed 

41971 implementation would use the default command interpreter if the one specified by the 

41972 environment variable was not available. This would allow a user, when using an application 

41973 that prompts for command lines to be processed using system^ ), to specify a different command 

41974 interpreter. Such an implementation is discouraged. If the alternate command interpreter did not 

41975 follow the command line syntax specified in the Commands and Utilities volume of 

41976 IEEE Std. 1003.1-200x, then changing SHELL would render system () non-conforming. This would 

41977 affect applications that expected the specified behavior from system( ), and since the Commands 

41978 and Utilities volume of IEEE Std. 1003.1-200x does not mention that SHELL affects system{ ), the 

41979 application would not know that it needed to unset SHELL. 

41980 FUTURE DIRECTIONS 

41981 None. 


41982 SEE ALSO 

41983 exec, pipe(), waitpid(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

41984 <limits.h>, <signal.h>, <stdlib.h>, <sys/wait.h>, the Commands and Utilities volume of 

41985 IEEE Std. 1003.1-200x 
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41986 

41987 

41988 

41989 

41990 

41991 

41992 

41993 

41994 

41995 

41996 

41997 

41998 

41999 

42000 

42001 

42002 

42003 


CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

Extensions beyond the ISO C standard are now marked. 

The following changes are incorporated for alignment with the ISO POSIX-2 standard: 

• The function is no longer marked as an extension. 

• The name of the argument is changed from string to command, and its type is changed from 

char* to const char*. 

• The DESCRIPTION and RETURN VALUE sections are completely replaced to bring them in 
line with the ISO POSIX-2 standard. They still describe essentially the same functionality, 
albeit that the definition is more complete. 

• The ERRORS section is changed to indicate that system () may return error values described 
for fork (). 

. The APPLICATION USAGE section is added. 

The following changes were made to align with the IEEE P1003.1a draft standard: I 

• The DESCRIPTION is adjusted to reflect the behavior on systems that do not support the I 

POSIX Shell option. I 
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42004 

42005 

42006 

42007 

42008 

42009 

42010 

42011 

42012 

42013 

42014 

42015 

42016 

42017 

42018 

42019 

42020 

42021 

42022 

42023 

42024 

42025 

42026 

42027 

42028 

42029 

42030 

42031 

42032 

42033 

42034 

42035 

42036 

42037 

42038 

42039 

42040 


NAME 

tan — tangent function 

SYNOPSIS 

#include <math.h> 

double tan(double x); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The tan () function shall compute the tangent of its argument x, measured in radians. 

An application wishing to check for error situations should set errno to 0 before calling tan(). If 
errno is non-zero on return, or the return value is NaN, an error has occurred. 

The tan () function may lose accuracy when its argument is far from 0.0. 

RETURN VALUE 

Upon successful completion, tan () shall return the tangent of x. 

xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM]. 

If x is ±Inf, either 0.0 shall be returned and errno set to [EDOM], or NaN shall be returned and 
errno may be set to [EDOM]. 

If the correct value would cause overflow, ±HUGE_VAL shall be returned and errno shall be set 
to [ERANGE], 

If the correct value would cause underflow, 0.0 shall be returned and errno may be set to 
[ERANGE], 

ERRORS 

The tan () function shall fail if: 

[ERANGE] The value to be returned would cause overflow. 

The tan () function may fail if: 
xsi [EDOM] The value x is NaN or ±Inf. 

[ERANGE] The value to be returned would cause underflow, 

xsi No other errors shall occur. 

EXAMPLES 

Taking the Tangent of a 45-Degree Angle 

#include <math.h> 

double radians = 45.0 * M_PI / 180; 
double result; 

result = tan (radians); 
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42041 APPLICATION USAGE 

42042 None. 

42043 RATIONALE 

42044 None. 

42045 FUTURE DIRECTIONS 

42046 None. 

42047 SEE ALSO 

42048 atari (), is nan (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 

42049 CHANGE HISTORY 

42050 First released in Issue 1. 

42051 Derived from Issue 1 of the SVID. 

42052 Issue 4 

42053 References to matherr( ) are removed. 

42054 The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 

42055 ISO C standard and to rationalize error handling in the mathematics functions. 

42056 The return value specified for [EDOM] is marked as an extension. 

42057 Issue 5 

42058 The last two paragraphs of the DESCRIPTION were included as APPLICATION USAGE notes 

42059 in previous issues. 
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42060 

42061 

42062 

42063 

42064 

42065 

42066 

42067 

42068 

42069 

42070 

42071 

42072 

42073 

42074 

42075 

42076 

42077 

42078 

42079 

42080 

42081 

42082 

42083 

42084 

42085 

42086 

42087 

42088 

42089 

42090 

42091 

42092 

42093 

42094 

42095 

42096 

42097 

42098 

42099 


NAME 

tanh — hyperbolic tangent function 

SYNOPSIS 

#include <math.h> 

double tanh(double x); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The tanh () function shall ompute the hyperbolic tangent of x. 

An application wishing to check for error situations should set errno to 0 before calling tanh(). If 
errno is non-zero on return, or the return value is NaN, an error has occurred. 

RETURN VALUE 

Upon successful completion, tanh () shall return the hyperbolic tangent of x. 

xsi If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

If the correct value would cause underflow, 0.0 shall be returned and errno may be set to 
[ERANGE], 

ERRORS 

The tanh () function may fail if: 
xsi [EDOM] The value of x is NaN. 

[ERANGE] The correct result would cause underflow, 

xsi No other errors shall occur. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

atanh(), is nan (), tan() r the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

<math.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

References to matherr () are removed. 

The RETURN VALUE and ERRORS sections are substantially rewritten for alignment with the 
ISO C standard and to rationalize error handling in the mathematics functions. 
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42100 

42101 

42102 

42103 


The return value specified for [EDOM] is marked as an extension. 

Issue 5 

The DESCRIPTION is updated to indicate how an application should check for an error. This 
text was previously published in the APPLICATION USAGE section. 
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42104 NAME 

42105 tcdrain — wait for transmission of output 

42106 SYNOPSIS 

42107 #include <termios.h> 


42108 int tcdrain (int fildes) ; 

42109 DESCRIPTION 

42110 The tcdrain () function shall wait until all output written to the object referred to by fildes is 

42111 transmitted. The fildes argument is an open file descriptor associated with a terminal. 

42112 Any attempts to use tcdrain () from a process which is a member of a background process group 

42113 on a fildes associated with its controlling terminal, shall cause the process group to be sent a 

42114 SIGTTOU signal. If the calling process is blocking or ignoring SIGTTOU signals, the process is 

42115 allowed to perform the operation, and no signal is sent. 

42116 RETURN VALUE 

42117 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 

42118 indicate the error. 


42119 ERRORS 

42120 The tcdrain () function shall fail if: 


42121 

42122 

42123 


[EBADF] 

[EINTR] 

[ENOTTY] 


Th e fildes argument is not a valid file descriptor. 
A signal interrupted tcdrain (). 

The file associated with fildes is not a terminal. 


42124 The tcdrain () function may fail if: 

42125 man [EIO] The process group of the writing process is orphaned, and the writing process 

42126 is not ignoring or blocking SIGTTOU. 

42127 EXAMPLES 

42128 None. 

42129 APPLICATION USAGE 

42130 None. 

42131 RATIONALE 

42132 None. 

42133 FUTURE DIRECTIONS 

42134 None. 

42135 SEE ALSO 

42136 tcflnsh{), the System Interface Definitions volume of IEEEStd. 1003.l-200x, <termios.h>, 

42137 <unistd.h>, the System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, I 

42138 General Terminal Interface I 

42139 CHANGE HISTORY 

42140 First released in Issue 3. 

42141 Entry included for alignment with the POSIX.1-1988 standard. 

42142 Issue 4 

42143 The [EIO] error is added to the ERRORS section. 

42144 The FUTURE DIRECTIONS section is added. 
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42145 

42146 

42147 

42148 

42149 

42150 

42151 

42152 

42153 

42154 


The following change is incorporated for alignment with the FIPS requirements: 

• The words "If _POSIXJOB_CONTROL is defined" are removed from the start of the second 
paragraph in the DESCRIPTION. This is because job control is defined as mandatory for 
Issue 4 conforming implementations. 

Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the DESCRIPTION, the final paragraph is no longer conditional on 
_POSIX JOB_CONTROL. This is a FIPS requirement. 

• The [EIO] error is added. 
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42155 NAME 

42156 tcflow — suspend or restart the transmission or reception of data 

42157 SYNOPSIS 

42158 #include <termios.h> 

42159 int tcflow (int fildes, int action) ; 

42160 DESCRIPTION 

42161 The tcflozv() function shall suspend or restart transmission or reception of data on the object 

42162 referred to by fildes, depending on the value of action. The fildes argument is an open file 

42163 descriptor associated with a terminal. 

42164 • If action is TCOOFF, output shall be suspended. 

42165 • If action is TCOON, suspended output shall be restarted. 

42166 • If action is TCIOFF, the system shall transmit a STOP character, which is intended to cause 

42167 the terminal device to stop transmitting data to the system. 

42168 • If action is TCION, the system shall transmit a START character, which is intended to cause 

42169 the terminal device to start transmitting data to the system. 

42170 The default on the opening of a terminal file is that neither its input nor its output are 

42171 suspended. 

42172 Attempts to use tcflow () from a process which is a member of a background process group on a 

42173 fildes associated with its controlling terminal, shall cause the process group to be sent a 

42174 SIGTTOU signal. If the calling process is blocking or ignoring SIGTTOU signals, the process is 

42175 allowed to perform the operation, and no signal is sent. 

42176 RETURN VALUE 

42177 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 

42178 indicate the error. 

42179 ERRORS 

42180 The tcflozv( ) function shall fail if: 

42181 [EBADF] The fildes argument is not a valid file descriptor. 

42182 [EINVAL] The action argument is not a supported value. 

42183 [ENOTTY] The file associated with fildes is not a terminal. 

42184 The tcflozv( ) function may fail if: 

42185 man [EIO] The process group of the writing process is orphaned, and the writing process 

42186 is not ignoring or blocking SIGTTOU. 

42187 EXAMPLES 

42188 None. 

42189 APPLICATION USAGE 

42190 None. 

42191 RATIONALE 

42192 None. 

42193 FUTURE DIRECTIONS 

42194 None. 
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42195 

42196 

42197 

42198 

42199 

42200 

42201 

42202 

42203 

42204 

42205 

42206 

42207 

42208 

42209 

42210 

42211 

42212 

42213 

42214 


SEE ALSO 

tcsendbreak (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <termios.h>, 
<unistd.h>, the System Interface Definitions volume of IEEE Std. 1003.l-200x, Chapter 11, I 
General Terminal Interface I 

CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the POSIX.1-1988 standard. 

Issue 4 

The descriptions of TCIOFF and TCION are reworded, indicating the intended consequences of 
transmitting stop and start characters. Issue 3 implied that these consequences were guaranteed. 

The [EIO] error is added to the ERRORS section. 

The FUTURE DIRECTIONS section is added. 

The following change is incorporated for alignment with the FIPS requirements: 

• The words "If _POSIX JOB_CONTROL is defined" are removed from the start of the second 
paragraph in the DESCRIPTION. This is because job control is defined as mandatory for 
Issue 4 conforming implementations. 

Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The [EIO] error is added. 
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42215 

42216 

42217 

42218 

42219 

42220 

42221 

42222 

42223 

42224 

42225 

42226 

42227 

42228 

42229 

42230 

42231 

42232 

42233 

42234 

42235 

42236 

42237 

42238 

42239 

42240 

42241 

42242 

42243 

42244 

42245 

42246 

42247 

42248 

42249 

42250 

42251 

42252 

42253 

42254 


NAME 

tcflush — flush non-transmitted output data, non-read input data, or both 

SYNOPSIS 

#include <termios.h> 

int tcflush(int fildes, int queue_selector ); 

DESCRIPTION 

Upon successful completion, tcflush () shall discard data written to the object referred to by fildes 
(an open file descriptor associated with a terminal) but not transmitted, or data received but not 
read, depending on the value of queue_selector\ 

• If queue_selector is TCIFLUSH, it shall flush data received but not read. 

• If queue_selector is TCOFLUSH, it shall flush data written but not transmitted. 

• If queue_selector is TCIOFLUSH, it shall flush both data received but not read and data 
written but not transmitted. 

Attempts to use tcflush () from a process which is a member of a background process group on a 
fildes associated with its controlling terminal, shall cause the process group to be sent a 
SIGTTOU signal. If the calling process is blocking or ignoring SIGTTOU signals, the process is 
allowed to perform the operation, and no signal is sent. 

RETURN VALUE 

Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 
indicate the error. 

ERRORS 

The tcflush () function shall fail if: 

[EBADF] The fildes argument is not a valid file descriptor. 

[EINVAL] The queue_selector argument is not a supported value. 

[ENOTTY] The file associated with fildes is not a terminal. 

The tcflush () function may fail if: 

man [EIO] The process group of the writing process is orphaned, and the writing process 

is not ignoring or blocking SIGTTOU. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

tcdrain (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <termios.h>, 
<unistd.h>, the System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, I 
General Terminal Interface I 


1390 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


tcflush() 


42255 

42256 

42257 

42258 

42259 

42260 

42261 

42262 

42263 

42264 

42265 

42266 

42267 

42268 

42269 

42270 

42271 

42272 

42273 

42274 


CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the POSIX.1-1988 standard. 

Issue 4 

The DESCRIPTION is modified to indicate that the flush operation only results if the call to 
tcflush() is successful. 

The [EIO] error is added to the ERRORS section. 

The FUTURE DIRECTIONS section is added. 

The following change is incorporated for alignment with the FIPS requirements: 

• The words "If _POSIX_JOB_CONTROL is defined" are removed from the start of the second 
paragraph in the DESCRIPTION. This is because job control is defined as mandatory for 
Issue 4 conforming implementations. 

Issue 6 

The Open Group corrigenda item U035/1 has been applied. In the ERRORS and APPLICATION 
USAGE sections, references to tcfloiu () are replaced with tcflush (). 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the DESCRIPTION, the final paragraph is no longer conditional on 
_POSIX JOB_CONTROL. This is a FIPS requirement. 

• The [EIO] error is added. 
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42275 

42276 

42277 

42278 

42279 

42280 

42281 

42282 

42283 

42284 

42285 

42286 

42287 

42288 

42289 

42290 

42291 

42292 

42293 

42294 

42295 

42296 

42297 

42298 

42299 

42300 

42301 

42302 

42303 

42304 

42305 

42306 

42307 

42308 

42309 

42310 

42311 

42312 

42313 

42314 

42315 

42316 

42317 


NAME 

tcgetattr — get the parameters associated with the terminal 

SYNOPSIS 

#include <termios.h> 

int tcgetattr(int fildes, struct termios *termios_p ); 

DESCRIPTION 

The tcgetattr () function shall get the parameters associated with the terminal referred to by fildes 
and store them in the termios structure referenced by termios_p. Th e fildes argument is an open 
file descriptor associated with a terminal. 

The termios_p argument is a pointer to a termios structure. 

The tcgetattr () operation is allowed from any process. 

If the terminal device supports different input and output baud rates, the baud rates stored in 
the termios structure returned by tcgetattr () shall reflect the actual baud rates, even if they are 
equal. If differing baud rates are not supported, the rate returned as the output baud rate shall be 
the actual baud rate. If the terminal device does not support split baud rates, the input baud rate 
stored in the termios structure shall be the output rate (as one of the symbolic values). 

RETURN VALUE 

Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 
indicate the error. 

ERRORS 

The tcgetattr () function shall fail if: 

[EBADF] Th e fildes argument is not a valid file descriptor. 

[ENOTTY] The file associated with fildes is not a terminal. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

Care must be taken when changing the terminal attributes. Applications should always do a 
tcgetattr (), save the termios structure values returned, and then do a tcsetattr () changing only 
the necessary fields. The application should use the values saved from the tcgetattr () to reset the 
terminal state whenever it is done with the terminal. This is necessary because terminal 
attributes apply to the underlying port and not to each individual open instance; that is, all 
processes that have used the terminal see the latest attribute changes. 

A program that uses these functions should be written to catch all signals and take other 
appropriate actions to ensure that when the program terminates, whether planned or not, the 
terminal device's state is restored to its original state. 

Existing practice dealing with error returns when only part of a request can be honored is based 
on calls to the ioctl() function. In historical BSD and System V implementations, the 
corresponding ioctl() returns zero if the requested actions were semantically correct, even if 
some of the requested changes could not be made. Many existing applications assume this 
behavior and would no longer work correctly if the return value were changed from zero to -1 
in this case. 
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42318 

42319 

42320 

42321 

42322 

42323 

42324 

42325 

42326 

42327 

42328 

42329 

42330 

42331 

42332 

42333 

42334 

42335 

42336 

42337 


Note that either specification has a problem. When zero is returned, it implies everything 
succeeded even if some of the changes were not made. When -1 is returned, it implies 
everything failed even though some of the changes were made. 

Applications that need all of the requested changes made to work properly should follow 
tcsetattr () with a call to tcgetattr () and compare the appropriate field values. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

tcsetattr(), the System Interface Definitions volume of IEEEStd. 1003.1-200x, <termios.h>, the I 
System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal I 
Interface I 

CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the POSIX.1-1988 standard. 

Issue 4 

The FUTURE DIRECTIONS section is added to allow for alignment with the ISO POSIX-1 
standard. 

Issue 6 

In the DESCRIPTION, the rate returned as the input baud rate shall be the output rate. 
Previously, the number zero was also allowed but was obsolescent. 
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42338 

42339 

42340 

42341 

42342 

42343 

42344 

42345 

42346 

42347 

42348 

42349 

42350 

42351 

42352 

42353 

42354 

42355 

42356 

42357 

42358 

42359 

42360 

42361 

42362 

42363 

42364 

42365 

42366 

42367 

42368 

42369 

42370 

42371 

42372 

42373 

42374 

42375 

42376 

42377 

42378 


NAME 

tcgetpgrp — get the foreground process group ID 

SYNOPSIS 

#include <unistd.h> 

pid_t tcgetpgrp(int fildes) ; 

DESCRIPTION 

The tcgetpgrp () function shall return the value of the process group ID of the foreground process 
group associated with the terminal. 

If there is no foreground process group, tcgetpgrp () returns a value greater than 1 that does not 
match the process group ID of any existing process group. 

The tcgetpgrp () function is allowed from a process that is a member of a background process 
group; however, the information may be subsequently changed by a process that is a member of 
a foreground process group. 

RETURN VALUE 

Upon successful completion, tcgetpgrp () shall return the value of the process group ID of the 
foreground process associated with the terminal. Otherwise, -1 shall be returned and errno set to 
indicate the error. 

ERRORS 

The tcgetpgrp () function shall fail if: 

[EBADF] The fildes argument is not a valid file descriptor. 

[ENOTTY] The calling process does not have a controlling terminal, or the file is not the 

controlling terminal. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

setsid (), setpgid(), tcsetpgrp(), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

<sys/types.h>, <unistd.h> 

CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the POSIX.1-1988 standard. 

Issue 4 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 
XSI-conformant systems. 

The <unistd.h> header is added to the SYNOPSIS section. 

The following change is incorporated for alignment with the FIPS requirements: 
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42379 

42380 

42381 

42382 

42383 

42384 

42385 

42386 

42387 

42388 

42389 


. The DESCRIPTION is clarified and the phrase "If _POSIXJOB_CONTROL is defined" is 
removed because job control is now mandatory on all XSI-conformant systems. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 

Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• In the DESCRIPTION, text previously conditional on support for _POSIX JOB_CONTROL is 
now mandatory. This is a FIPS requirement. 
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42391 

42392 

42393 

42394 

42395 

42396 

42397 

42398 

42399 

42400 

42401 

42402 

42403 

42404 

42405 

42406 

42407 

42408 

42409 

42410 

42411 

42412 

42413 

42414 

42415 

42416 

42417 

42418 

42419 

42420 

42421 

42422 


NAME 

tcgetsid — get process group ID for session leader for controlling terminal 

SYNOPSIS 

xsi tinclude <termios.h> 

pid_t tcgetsid(int fildes) ; 


DESCRIPTION 

The tcgetsid() function shall obtain the process group ID of the session for which the terminal 
specified by fildes is the controlling terminal. 

RETURN VALUE 

Upon successful completion, tcgetsid () shall return the process group ID associated with the 
terminal. Otherwise, a value of (pid_t)-l shall be returned and errno set to indicate the error. 

ERRORS 

The tcgetsid() function shall fail if: 

[EBADF] The fildes argument is not a valid file descriptor. 

[ENOTTY] The calling process does not have a controlling terminal, or the file is not the 

controlling terminal. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

The System Interface Definitions volume of IEEE Std. 1003.1-200x, <termios.h> 

CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 

The [EACCES] error has been removed from the list of mandatory errors, and the description of 
[ENOTTY] has been reworded. 
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42423 NAME 

42424 tcsendbreak — send a "break” for a specific duration 

42425 SYNOPSIS 

42426 #include <termios.h> 

42427 int tcsendbreak (int fildes, int duration) ; 

42428 DESCRIPTION 

42429 Th e fildes argument is an open file descriptor associated with a terminal. 

42430 If the terminal is using asynchronous serial data transmission, tcsendbreak() shall cause 

42431 transmission of a continuous stream of zero-valued bits for a specific duration. If duration is 0, it 

42432 shall cause transmission of zero-valued bits for at least 0.25 seconds, and not more than 0.5 

42433 seconds. If duration is not 0, it shall send zero-valued bits for an implementation-dependent 

42434 period of time. 

42435 If the terminal is not using asynchronous serial data transmission, it is implementation- 

42436 dependent whether tcsendbreak() sends data to generate a break condition or returns without 

42437 taking any action. 

42438 Attempts to use tcsendbreak( ) from a process which is a member of a background process group 

42439 on a fildes associated with its controlling terminal, shall cause the process group to be sent a 

42440 SIGTTOU signal. If the calling process is blocking or ignoring SIGTTOU signals, the process is 

42441 allowed to perform the operation, and no signal is sent. 

42442 RETURN VALUE 

42443 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 

42444 indicate the error. 

42445 ERRORS 

42446 The tcsendbreak( ) function shall fail if: 

42447 [EBADF] The fildes argument is not a valid file descriptor. 

42448 [ENOTTY] The file associated with fildes is not a terminal. 

42449 The tcsendbreak () function may fail if: 

42450 man [EIO] The process group of the writing process is orphaned, and the writing process 

42451 is not ignoring or blocking SIGTTOU. 

42452 EXAMPLES 

42453 None. 

42454 APPLICATION USAGE 

42455 None. 

42456 RATIONALE 

42457 None. 

42458 FUTURE DIRECTIONS 

42459 None. 

42460 SEE ALSO 

42461 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <termios.h>, <unistd.h>, the I 

42462 System Interface Definitions volume of IEEE Std. 1003.l-200x. Chapter 11, General Terminal I 

42463 Interface I 
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42465 

42466 

42467 

42468 

42469 

42470 

42471 

42472 

42473 

42474 

42475 

42476 

42477 


CHANGE HISTORY 

First released in Issue 3. 

Entry included for alignment with the POSIX.1-1988 standard. 

Issue 4 

The [EIO] error is added to the ERRORS section. 

The following change is incorporated for alignment with the FIPS requirements: 

. In the DESCRIPTION the phrase "If _POSIXJOB_CONTROL is defined" is removed 
because job control is now mandatory on all XSI-conformant systems. 

Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the DESCRIPTION, text previously conditional on POSIX JOB CONTROL is now 
mandated. This is a FIPS requirement. 

• The [EIO] error is added. 
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42478 NAME 

42479 tcsetattr — set the parameters associated with the terminal 

42480 Notes to Reviewers 

42481 This section zvith side shading will not appear in the final copy. - Ed. 

42482 See the FUTURE DIRECTIONS section. 

42483 SYNOPSIS 

42484 #include <termios.h> 

42485 int tcsetattr (int fildes, int optional_actions , 

42486 const struct termios *termios_p) ; 

42487 DESCRIPTION 

42488 The tcsetattr () function shall set the parameters associated with the terminal referred to by the 

42489 open file descriptor fildes (an open file descriptor associated with a terminal) from the termios 

42490 structure referenced by termios_p as follows: 

42491 • If optional_actions is TCSANOW, the change shall occur immediately. 

42492 • If optional_actions is TCSADRAIN, the change shall occur after all output written to fildes is 

42493 transmitted. This function should be used when changing parameters that affect output. 

42494 • If optional_actions is TCSAFLUSH, the change shall occur after all output written to fildes is 

42495 transmitted, and all input so far received but not read shall be discarded before the change is 

42496 made. 

42497 If the output baud rate stored in the termios structure pointed to by termios_p is the zero baud 

42498 rate, BO, the modem control lines shall no longer be asserted. Normally, this shall disconnect the 

42499 line. 

42500 If the input baud rate stored in the termios structure pointed to by termios_p is 0, the input baud 

42501 rate given to the hardware is the same as the output baud rate stored in the termios structure. 

42502 The tcsetattr () function shall return successfully if it was able to perform any of the requested 

42503 actions, even if some of the requested actions could not be performed. It shall set all the 

42504 attributes that the implementation supports as requested and leaves all the attributes not 

42505 supported by the implementation unchanged. If no part of the request can be honored, it shall 

42506 return -1 and set errno to [EINVAL]. If the input and output baud rates differ and are a 

42507 combination that is not supported, neither baud rate is changed. A subsequent call to tcgetattr () 

42508 shall return the actual state of the terminal device (reflecting both the changes made and not 

42509 made in the previous tcsetattr() call). The tcsetattr () function shall not change the values found 

42510 in the termios structure under any circumstances. 

42511 The effect of tcsetattr () is undefined if the value of the termios structure pointed to by termios_p 

42512 was not derived from the result of a call to tcgetattr() on fildes; an application should modify 

42513 only fields and flags defined by this volume of IEEE Std. 1003.1-200x between the call to 

42514 tcgetattr( ) and tcsetattr (), leaving all other fields and flags unmodified. 

42515 No actions defined by this volume of IEEE Std. 1003.1-200x, other than a call to tcsetattr () or a 

42516 close of the last file descriptor in the system associated with this terminal device, shall cause any 

42517 of the terminal attributes defined by this volume of IEEE Std. 1003.1-200x to change. 

42518 If tcsetattr () is called from a process which is a member of a background process group on a 

42519 fildes associated with its controlling terminal: 

42520 • If the calling process is blocking or ignoring SIGTTOU signals, the operation completes 

42521 normally and no signal is sent. 
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42522 • Otherwise, a SIGTTOU signal shall be sent to the process group. 

42523 RETURN VALUE 

42524 Upon successful completion, 0 shall be shall be. Otherwise, -1 shall be returned and errno set to 

42525 indicate the error. 

42526 ERRORS 

42527 The tcsetattr( ) function shall fail if: 

42528 [EBADF] Th efildes argument is not a valid file descriptor. 

42529 [EINTR] A signal interrupted tcsetattr {). 

42530 [EINVAL] The optional_actions argument is not a supported value, or an attempt was 

42531 made to change an attribute represented in the termios structure to an 

42532 unsupported value. 

42533 [ENOTTY] The file associated with fildes is not a terminal. 

42534 The tcsetattr( ) function may fail if: 

42535 man [EIO] The process group of the writing process is orphaned, and the writing process 

42536 is not ignoring or blocking SIGTTOU. 

42537 EXAMPLES 

42538 None. 

42539 APPLICATION USAGE 

42540 If trying to change baud rates, applications should call tcsetattr( ) then call tcgetattr( ) in order to 

42541 determine what baud rates were actually selected. 

42542 RATIONALE 

42543 The tcsetattr( ) function can be interrupted in the following situations: 

42544 • It is interrupted while waiting for output to drain. 

42545 • It is called from a process in a background process group and SIGTTOU is caught. 

42546 See also the RATIONALE section in tcgetattr( ). 

42547 FUTURE DIRECTIONS 

42548 Using an input baud rate of 0 to set the input rate equal to the output rate may not necessarily be 

42549 supported in a future version of this volume of IEEE Std. 1003.1-200x. 

42550 SEE ALSO 

42551 cfgetispeed(), tcgetattr(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

42552 <termios.h>, <unistd.h>, the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 

42553 Chapter 11, General Terminal Interface I 

42554 CHANGE HISTORY 

42555 First released in Issue 3. 

42556 Entry included for alignment with the POSIX.1-1988 standard. 

42557 Issue 4 

42558 The words "and stores them in" are changed to "from" in the first paragraph of the 

42559 DESCRIPTION. 

42560 The [EINTR] and [EIO] errors are added to the ERRORS section. 

42561 The FUTURE DIRECTIONS section is added to allow for alignment with the ISO POSIX-1 

42562 standard. 
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42563 

42564 

42565 

42566 

42567 

42568 

42569 

42570 

42571 

42572 

42573 

42574 

42575 


The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The argument termiosjp is changed from type struct termios* to const struct termios*. 

The following change is incorporated for alignment with the FIPS requirements: 

. In the DESCRIPTION the phrase "If _POSIXJOB_CONTROL is defined" is removed 
because job control is now mandatory on all XSI-conformant systems. 

Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the DESCRIPTION, text previously conditional on _POSIX_JOB_CONTROL is now 
mandated. This is a FIPS requirement. 

• The [EIO] error is added. 

In the DESCRIPTION, the text describing use of tcsetattr () from a process which is a member of 
a background process group is clarified. 
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42576 NAME 

42577 tcsetpgrp — set the foreground process group ID 

42578 SYNOPSIS 

42579 #include <unistd.h> 

42580 int tcsetpgrp (int fildes, pid_t pgid_id) ; 

42581 DESCRIPTION 

42582 If the process has a controlling terminal, tcsetpgrp () shall set the foreground process group ID 

42583 associated with the terminal to pgid_id. The application shall ensure that the file associated with I 

42584 fildes is the controlling terminal of the calling process and the controlling terminal is currently I 

42585 associated with the session of the calling process. The application shall ensure that the value of I 

42586 pgid_id matches a process group ID of a process in the same session as the calling process. I 

42587 RETURN VALUE 

42588 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 

42589 indicate the error. 

42590 ERRORS 

42591 The tcsetpgrp () function shall fail if: 

42592 [EBADF] Th e fildes argument is not a valid file descriptor. 

42593 [EINVAL] This implementation does not support the value in the pgid_id argument. 

42594 [ENOTTY] The calling process does not have a controlling terminal, or the file is not the 

42595 controlling terminal, or the controlling terminal is no longer associated with 

42596 the session of the calling process. 

42597 [EPERM] The value of pgid_id is a value supported by the implementation, but does not 

42598 match the process group ID of a process in the same session as the calling 

42599 process. 

42600 EXAMPLES 

42601 None. 

42602 APPLICATION USAGE 

42603 None. 

42604 RATIONALE 

42605 None. 

42606 FUTURE DIRECTIONS 

42607 None. 

42608 SEE ALSO 

42609 tcgetpgrp (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <sys/types.h>, 

42610 <unistd.h> 

42611 CHANGE HISTORY 

42612 First released in Issue 3. 

42613 Entry included for alignment with the POSIX.1-1988 standard. 

42614 Issue 4 

42615 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

42616 XSI-conformant systems. 

42617 The <unistd.h> header is added to the SYNOPSIS section. 
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42618 

42619 

42620 

42621 

42622 

42623 

42624 

42625 

42626 

42627 

42628 

42629 

42630 

42631 


The [ENOSYS] error is removed from the ERRORS section. 

The following change is incorporated for alignment with the FIPS requirements: 

. In the DESCRIPTION the phrase "If _POSIXJOB_CONTROL is defined" is removed 
because job control is now mandatory on all XSI-conformant systems. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 

Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• In the DESCRIPTION and ERRORS sections, text previously conditional on 
_POSIXJOB_CONTROL is now mandated. This is a FIPS requirement. 

The DESCRIPTION is updated to avoid use of the term "must" for application requirements. 
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42632 NAME 

42633 tdelete — delete node from binary search tree 

42634 SYNOPSIS 

42635 xsi #include <search.h> 

42636 void *tdelete(const void *key, void **rootp, 

42637 int (* compar) (const void *, const void *)); 

42638 

42639 DESCRIPTION 

42640 Refer to tsearch (). 
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42641 

42642 

42643 

42644 

42645 

42646 

42647 

42648 

42649 

42650 

42651 

42652 

42653 

42654 

42655 

42656 

42657 

42658 

42659 

42660 

42661 

42662 

42663 

42664 

42665 

42666 

42667 

42668 

42669 

42670 

42671 

42672 

42673 

42674 

42675 


NAME 

telldir — current location of a named directory stream 

SYNOPSIS 

xsi tinclude <dirent.h> 

long int telldir(DIR *dirp); 


DESCRIPTION 

The telldir( ) function obtains the current location associated with the directory stream specified 
by dirp. 

If the most recent operation on the directory stream was a seekdiri), the directory position 
returned from the telldir () shall be the same as that supplied as a loc argument for seekdir {). 

RETURN VALUE 

Upon successful completion, telldir() shall return the current location of the specified directory 
stream. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

opendir(), readdir(), seekdir(), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

<dirent.h> 

CHANGE HISTORY 

First released in Issue 2. 


Issue 4 

The <sys/types.h> header is removed from the SYNOPSIS section. 
The function return value is expanded to long int. 


Issue 4, Version 2 

The DESCRIPTION is updated for X/OPEN UNIX conformance to indicate that a call to telldir () 
immediately following a call to seekdir( ), returns the loc value passed to the seekdir( ) call. 
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42676 NAME 

42677 tempnam — create a name for a temporary file 

42678 SYNOPSIS 

42679 xsi #include <stdio.h> 

42680 char *tempnam (const char *dir, const char *pfx) ; 

42681 

42682 DESCRIPTION 

42683 The tempnam () function generates a path name that may be used for a temporary file. 

42684 The tempnam () function allows the user to control the choice of a directory. The dir argument 

42685 points to the name of the directory in which the file is to be created. If dir is a null pointer or 

42686 points to a string which is not a name for an appropriate directory, the path prefix defined as 

42687 P_tmpdir in the <stdio.h> header is used. If that directory is not accessible, an implementation- 

42688 dependent directory may be used. 

42689 Many applications prefer their temporary files to have certain initial letter sequences in their 

42690 names. The pfx argument should be used for this. This argument may be a null pointer or point 

42691 to a string of up to five bytes to be used as the beginning of the file name. 

42692 Some implementations of tempnam () may use tmpnam( ) internally. On such implementations, if 

42693 called more than {TMP_MAX} times in a single process, the behavior is implementation- 

42694 dependent. 

42695 RETURN VALUE 

42696 Upon successful completion, tempnam( ) shall allocate space for a string, put the generated path 

42697 name in that space, and return a pointer to it. The pointer shall be suitable for use in a 

42698 subsequent call to free (). Otherwise, it shall return a null pointer and set errno to indicate the 

42699 error. 

42700 ERRORS 

42701 The tempnam () function shall fail if: 

42702 [ENOMEM] Insufficient storage space is available. 

42703 EXAMPLES 

42704 Generating a Path Name 

42705 The following example generates a path name for a temporary file in directory /tmp, with the 

42706 prefix file. After the file name has been created, the call to free () deallocates the space used to 

42707 store the file name. 

42708 #include <stdio.h> 

42709 #include <stdlib.h> 

42710 

42711 char *directory = "/tmp"; 

42712 char *fileprefix = "file"; 

42713 char *file; 

42714 file = tempnam (directory, fileprefix) ; 

42715 free (file); 
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42716 APPLICATION USAGE 

42717 This function only creates path names. It is the application's responsibility to create and remove 

42718 the files. Between the time a path name is created and the file is opened, it is possible for some 

42719 other process to create a file with the same name. Applications may find tmpfile () more useful. 

42720 RATIONALE 

42721 None. 

42722 FUTURE DIRECTIONS 

42723 None. 

42724 SEE ALSO 

42725 fopen(),free(), open(), tmpfile(), tmpnam{), unlink(), the System Interface Definitions volume of 

42726 IEEE Std. 1003.1-200x, <stdio.h> 

42727 CHANGE HISTORY 

42728 First released in Issue 1. 

42729 Derived from Issue 1 of the SVID. 

42730 Issue 4 

42731 The type of arguments dir and pfx is changed from char 5 '' to const char’''. 

42732 The DESCRIPTION is changed to indicate that pfx is treated as a string of bytes and not as a 

42733 string of (possibly multi-byte) characters. 

42734 The second paragraph of the APPLICATION USAGE section is expanded. 

42735 Issue 5 

42736 The last paragraph of the DESCRIPTION was included as an APPLICATION USAGE note in 

42737 previous issues. 
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42738 NAME 

42739 tfind — search binary search tree 

42740 SYNOPSIS 

42741 xsi #include <search.h> 

42742 void *tfind (const void *key, 

42743 int (* compar) (const void 

42744 

42745 DESCRIPTION 

42746 Refer to tsearch (). 


void *const *rootp, 
*, const void *) ) ; 
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42747 NAME 

42748 time — get time 

42749 SYNOPSIS 

42750 tinclude <time.h> 

42751 time_t time (time_t *tloc); 

42752 DESCRIPTION 

42753 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

42754 conflict between the requirements described here and the ISO C standard is unintentional. This I 

42755 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

42756 cx The time {) function returns the value of time in seconds since the Epoch. 

42757 The tloc argument points to an area where the return value is also stored. If tloc is a null pointer, 

42758 no value is stored. 

42759 RETURN VALUE 

42760 Upon successful completion, time () shall return the value of time. Otherwise, (time_t)-l shall be 

42761 returned. 

42762 ERRORS 

42763 No errors are defined. 

42764 EXAMPLES 

42765 Getting the Current Time 

42766 The following example uses the time {) function to calculate the time elapsed, in seconds, since 

42767 January 1,1970 0:00 UTC, localtime () to convert that value to a broken-down time, and asctime( ) 

42768 to convert the broken-down time values into a printable string. 

42769 #include <stdio.h> 

42770 #include <time.h> 

42771 main () 

42772 { 

42773 time_t result; 

42774 result = time (NULL) ; 

42775 printf ("%s%ld secs since the Epoch\n", 

42776 asctime (localtime (Sresult) ) , 

42777 (long) result) ; 

42778 return (0); 

42779 } 

42780 This example writes the current time to stdont in a form like this: 

42781 Wed Jun 26 10:32:15 1996 

42782 8 3 5 8 1 0 3 3 5 secs since the Epoch 
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42783 Timing an Event 

42784 The following example gets the current time, prints it out in the user's format, and prints the 

42785 number of minutes to an event being timed. 

42786 #include <time.h> 

42787 #include <stdio.h> 

42788 

42789 time_t now; 

42790 int minutes_to_event; 

42791 

42792 time (Snow) ; 

42793 printf ("The time is "); 

42794 puts (asctime (localtime (Snow) ) ) ; 

42795 printf ("There are %d minutes to the event.\n", 

42796 minutes_to_event) ; 

42797 

42798 APPLICATION USAGE 

42799 None. 

42800 RATIONALE 

42801 The time{ ) function returns a value in seconds (type time_t) while times () returns a set of values 

42802 in clock ticks (type clock_t). Some historical implementations, such as 4.3 BSD, have 

42803 mechanisms capable of returning more precise times (see below). A generalized timing scheme 

42804 to unify these various timing mechanisms has been proposed but not adopted. 

42805 Implementations in which time_t is a 32-bit signed integer (many historical implementations) 

42806 fail in the year 2038. This issue of this volume of IEEE Std. 1003.1-200x does not address this 

42807 problem. However, the use of the time_t type is mandated in order to ease the eventual fix. 

42808 The use of the <time.h>, header instead of <sys/types.h>, allows compatibility with the ISO C 

42809 standard. 

42810 Many historical implementations (including Version 7) and the 1984 /usr/group standard use 

42811 long instead of time_t This volume of IEEE Std. 1003.1-200x uses the latter type in order to 

42812 agree with the ISO C standard. 

42813 4.3 BSD includes time( ) only as an function to the more flexible gettimeofday () function. 

42814 FUTURE DIRECTIONS 

42815 In a future version of this volume of IEEE Std. 1003.1-200x, time_t is likely to be required to be 

42816 capable of representing times far in the future. Whether this will be mandated as a 64-bit type or 

42817 a requirement that a specific date in the future be representable (for example, 10000 AD) is not 

42818 yet determined. Systems purchased after the approval of this volume of IEEE Std. 1003.1-200x 

42819 should be evaluated to determine whether their lifetime will extend past 2038. 

42820 SEE ALSO 

42821 asctime (), clock (), ctime (), d iff time (), gmtime (), localtime(), mktime (), strftime (), strptime( ), utime{ ), 

42822 the System Interface Definitions volume of IEEE Std. 1003.1-200x, <time.h> 

42823 CHANGE HISTORY 

42824 First released in Issue 1. 

42825 Derived from Issue 1 of the SVID. 
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42826 Issue 4 

42827 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

42828 • The RETURN VALUE section is updated to indicate that (time_t)-l is returned on error. 


42829 Issue 6 

42830 Extensions beyond the ISO C standard are now marked. 
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42831 

42832 

42833 

42834 

42835 

42836 

42837 

42838 
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NAME 

timer_create — create a per-process timer (REALTIME) 

SYNOPSIS 

tmr #include <signal.h> 

#include <time.h> 

int timer_create(clockid_t clockid, struct sigevent *evp, 
timer_t *timerid); 


DESCRIPTION 

The timer_create( ) function shall create a per-process timer using the specified clock, clock_id, as 
the timing base. The timer_create( ) function returns, in the location referenced by timerid, a timer 
ID of type timer_t used to identify the timer in timer requests. This timer ID shall be unique 
within the calling process until the timer is deleted. The particular clock, clock_id, is defined in 
<time.h>. The timer whose ID is returned shall be in a disarmed state upon return from 
timer_create (). 

The evp argument, if non-NULL, points to a sigevent structure. This structure, allocated by the 
application, defines the asynchronous notification to occur as specified in Section 2.4.1 on page 
43 when the timer expires. If the evp argument is NULL, the effect is as if the evp argument 
pointed to a sigevent structure with the sigev_notify member having the value SIGEV_SIGNAL, 
the sigev_signo having a default signal number, and the sigevjpalue member having the value of 
the timer ID. 

Each implementation shall define a set of clocks that can be used as timing bases for per-process 
mon timers. All implementations shall support a clock_id of CLOCK_REALTIME. If the Monotonic 
Clock option is supported, all implementations shall support a clockjd of 
CLOCK_MONOTONIC. 

Per-process timers shall not be inherited by a child process across a fork () and shall be disarmed 
and deleted by an exec. 

cpt If _POSIX_CPUTIME is defined, implementations shall support clockjd values representing the 
CPU-time clock of the calling process. 

tct If _POSIX_THREAD_CPUTIME is defined, implementations shall support clockjd values 
representing the CPU-time clock of the calling thread. 

cpt i tct It is implementation-dependent whether a timer_create{) function will succeed if the value 
defined by clockjd corresponds to the CPU-time clock of a process or thread different from the 
process or thread invoking the function. 

RETURN VALUE 

If the call succeeds, timer_create( ) shall return zero and update the location referenced by timerid 
to a timer_t, which can be passed to the per-process timer calls. If an error occurs, the function 
shall return a value of -1 and set errno to indicate the error. The value of timerid is undefined if 
an error occurs. 

ERRORS 

The timer_create( ) function shall fail if: 

[EAGAIN] The system lacks sufficient signal queuing resources to honor the request. 

[EAGAIN] The calling process has already created all of the timers it is allowed by this 

implementation. 
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[EINVAL] 

[ENOTSUP] 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

Periodic Timer Overrun and Resource Allocation 

The specified timer facilities may deliver realtime signals (that is, queued signals) on 
implementations that support this option. Because realtime applications cannot afford to lose 
notifications of asynchronous events, like timer expirations or asynchronous I/O completions, it 
must be possible to ensure that sufficient resources exist to deliver the signal when the event 
occurs. In general, this is not a difficulty because there is a one-to-one correspondence between a 
request and a subsequent signal generation. If the request cannot allocate the signal delivery 
resources, it can fail the call with an [EAGAIN] error. 

Periodic timers are a special case. A single request can generate an indeterminate number of 
signals. This is not a problem if the requesting process can service the signals as fast as they are 
generated, thus making the signal delivery resources available for delivery of subsequent 
periodic timer expiration signals. But, in general, this cannot be assured—processing of periodic 
timer signals may "overrun”; that is, subsequent periodic timer expirations may occur before the 
currently pending signal has been delivered. 

Also, for signals, according to the POSIX.1-1990 standard, if subsequent occurrences of a 
pending signal are generated, it is implementation-dependent whether a signal is delivered for 
each occurrence. This is not adequate for some realtime applications. So a mechanism is required 
to allow applications to detect how many timer expirations were delayed without requiring an 
indefinite amount of system resources to store the delayed expirations. 

The specified facilities provide for an overrun count. The overrun count is defined as the number 
of extra timer expirations that occurred between the time a timer expiration signal is generated 
and the time the signal is delivered. The signal-catching function, if it is concerned with 
overruns, can retrieve this count on entry. With this method, a periodic timer only needs one 
"signal queuing resource" that can be allocated at the time of the timer_create () function call. 

A function is defined to retrieve the overrun count so that an application need not allocate static 
storage to contain the count, and an implementation need not update this storage 
asynchronously on timer expirations. But, for some high-frequency periodic applications, the 
overhead of an additional system call on each timer expiration may be prohibitive. The 
functions, as defined, permit an implementation to maintain the overrun count in user space, 
associated with the timerid. The timer_getoverrun () function can then be implemented as a macro 
that uses the timerid argument (which may just be a pointer to a user space structure containing 
the counter) to locate the overrun count with no system call overhead. Other implementations, 
less concerned with this class of applications, can avoid the asynchronous update of user space 
by maintaining the count in a system structure at the cost of the extra system call to obtain it. 
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The specified clock ID is not defined. I 

The implementation does not support the creation of a timer attached to the I 
CPU-time clock which is specified by clock_id and associated with a process or I 
thread different from the process or thread invoking timer_create (). I 
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42918 Timer Expiration Signal Parameters 

42919 The Realtime Signals Extension option supports an application-specific datum that is delivered 

42920 to the extended signal handler. This value is explicitly specified by the application, along with 

42921 the signal number to be delivered, in a sigevent structure. The type of the application-defined 

42922 value can be either an integer constant or a pointer. This explicit specification of the value, as 

42923 opposed to always sending the timer ID, was selected based on existing practice. 

42924 It is common practice for realtime applications (on non-POSIX systems or realtime extended 

42925 POSIX systems) to use the parameters of event handlers as the case label of a switch statement 

42926 or as a pointer to an application-defined data structure. Because timer_ids are dynamically 

42927 allocated by the timer_create( ) function, they can be used for neither of these functions without 

42928 additional application overhead in the signal handler; for example, to search an array of saved 

42929 timer IDs to associate the ID with a constant or application data structure. 

42930 FUTURE DIRECTIONS 

42931 None. 

42932 SEE ALSO 

42933 clock_getres(), timer_delete(), timer_getoverrun (), the System Interface Definitions volume of 

42934 IEEE Std. 1003.1-200x, <time.h> 

42935 CHANGE HISTORY 

42936 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. I 

42937 Issue 6 

42938 The timer_create{) function is marked as part of the _POSIX_TIMERS option. 

42939 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

42940 implementation does not support the _POSIX_TIMERS option. I 

42941 CPU-time clocks are added for alignment with IEEE Std. 1003.1d-1999. I 

42942 The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by adding the I 

42943 requirement for the CLOCK_MONOTONIC clock under the Monotonic Clock option. I 
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42944 NAME 

42945 timer_delete — delete a per-process timer (REALTIME) 

42946 SYNOPSIS 

42947 tmr #include <time.h> 

42948 int timer_delete (timer_t timerid ) ; 

42949 

42950 DESCRIPTION 

42951 The timer_delete{ ) function deletes the specified timer, timerid, previously created by the 

42952 timer_create( ) function. If the timer is armed when timer_delete( ) is called, the behavior shall be 

42953 as if the timer is automatically disarmed before removal. The disposition of pending signals for 

42954 the deleted timer is unspecified. 

42955 RETURN VALUE 

42956 If successful, the timer_delete{) function shall return a value of zero. Otherwise, the function shall 

42957 return a value of -1 and set errno to indicate the error. 

42958 ERRORS 

42959 The timer_delete( ) function shall fail if: 

42960 [EINVAL] The timer ID specified by timerid is not a valid timer ID. 

42961 EXAMPLES 

42962 None. 

42963 APPLICATION USAGE 

42964 None. 

42965 RATIONALE 

42966 None. 

42967 FUTURE DIRECTIONS 

42968 None. 

42969 SEE ALSO 

42970 timer_create( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <time.h> 

42971 CHANGE HISTORY 

42972 First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

42973 Issue 6 

42974 The timer_delete( ) function is marked as part of the _POSIX_TIMERS option. 

42975 The [ENOSYS] error condition has been removed as stubs need not be provided if an 

42976 implementation does not support the _POSIX_TIMERS option. 
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42977 NAME 

42978 timer_getoverrun, timer_gettime, timer_settime — per-process timers (REALTIME) 

42979 SYNOPSIS 

42980 TMR 

42981 

42982 

42983 

42984 

42985 

42986 DESCRIPTION 

42987 Only a single signal shall be queued to the process for a given timer at any point in time. When a 

42988 timer for which a signal is still pending expires, no signal shall be queued, and a timer overrun 

42989 rts shall occur. When a timer expiration signal is delivered to or accepted by a process, if the 

42990 implementation supports the Realtime Signals Extension, the timer_getoverrun () function returns 

42991 the timer expiration overrun count for the specified timer. The overrun count returned contains 

42992 the number of extra timer expirations that occurred between the time the signal was generated 

42993 (queued) and when it was delivered or accepted, up to but not including an implementation- 

42994 dependent maximum of |DELAYTIMER_MAX}. If the number of such extra expirations is 

42995 greater than or equal to |DELAYTIMER_MAX}, then the overrun count is set to 

42996 {DELAYTIMER_MAX}. The value returned by timer_getoverrun () applies to the most recent 

42997 expiration signal delivery or acceptance for the timer. If no expiration signal has been delivered 

42998 for the timer, or if the Realtime Signals Extension is not supported, the return value of 

42999 timer_getoverrnn () is unspecified. 

43000 The timer_gettime() function shall store the amount of time until the specified timer, timerid, 

43001 expires and the reload value of the timer into the space pointed to by the value argument. The 

43002 it_value member of this structure shall contain the amount of time before the timer expires, or 

43003 zero if the timer is disarmed. This value is returned as the interval until timer expiration, even if 

43004 the timer was armed with absolute time. The it_interval member of value shall contain the reload 

43005 value last set by timer_settime( ). 

43006 The timer_settime{ ) function shal set the time until the next expiration of the timer specified by 

43007 timerid from the it_value member of the value argument and arms the timer if the it_value 

43008 member of value is non-zero. If the specified timer was already armed when timer_settime () is 

43009 called, this call shall reset the time until next expiration to the value specified. If the it_value 

43010 member of value is zero, the timer shall be disarmed. The effect of disarming or resetting a timer 

43011 on pending expiration notifications is unspecified. 

43012 If the flag TIMER_ABSTIME is not set in the argument flags, timerjsettime{) behaves as if the 

43013 time until next expiration is set to be equal to the interval specified by the it_value member of 

43014 value. That is, the timer shall expire in it_value nanoseconds from when the call is made. If the 

43015 flag TIMER_ABSTIME is set in the argument flags, timer_settime() behaves as if the time until 

43016 next expiration is set to be equal to the difference between the absolute time specified by the 

43017 it_value member of value and the current value of the clock associated with timerid. That is, the 

43018 timer shal expire when the clock reaches the value specified by the it_value member of value. If 

43019 the specified time has already passed, the function shall succeed and the expiration notification 

43020 shall be made. 

43021 The reload value of the timer is set to the value specified by the it_interval member of value. 

43022 When a timer is armed with a non-zero it_interval, a periodic (or repetitive) timer is specified. 

43023 Time values that are between two consecutive non-negative integer multiples of the resolution 

43024 of the specified timer shall be rounded up to the larger multiple of the resolution. Quantization 


#include <time.h> 

int timer_getoverrun(timer_t timerid); 

int timer_gettime(timer_t timerid, struct itimerspec *value) ; 
int timer_settime(timer_t timerid, int flags, 

const struct itimerspec *value, struct itimerspec * ovalue) ; 


1416 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


timer_getoverrun() 


43025 error shall not cause the timer to expire earlier than the rounded time value. 

43026 If the argument ovalue is not NULL, the function timer_settime{ ) shall store, in the location 

43027 referenced by ovalue, a value representing the previous amount of time before the timer would 

43028 have expired, or zero if the timer was disarmed, together with the previous timer reload value. 

43029 Notes to Reviewers 

43030 This section with side shading will not appear in the final copy. - Ed. 

43031 Dl, XSH, ERN 388 suggests rewording "are subject to the resolution of the timer" to "may have 

43032 been rounded to the resolution of the timer". 

43033 The members of ovalue are subject to the resolution of the timer, and they are the same values 

43034 that would be returned by a timer_gettime () call at that point in time. 

43035 RETURN VALUE 

43036 If the timer_getoverrun () function succeeds, it shall return the timer expiration overrun count as 

43037 explained above. 

43038 If the timer_gettime ( ) or timer_settime ( ) functions succeed, a value of 0 shall be returned. 

43039 If an error occurs for any of these functions, the value -1 shall be returned, and errno set to 

43040 indicate the error. 

43041 ERRORS 

43042 The timer_getoverrun (), timer_gettime (), and timer_settime () functions shall if: 

43043 [EINVAL] The timerid argument does not correspond to an ID returned by timer_create{ ) 

43044 but not yet deleted by timer_delete( ). 

43045 The timer_settime () function shall fail if: 

43046 [EINVAL] A value structure specified a nanosecond value less than zero or greater than 

43047 man or equal to 1,000 million, and the it_value member of that structure did not 

43048 specify zero seconds and nanoseconds. 

43049 EXAMPLES 

43050 None. 

43051 APPLICATION USAGE 

43052 None. 

43053 RATIONALE 

43054 The clock_settime(), timer_settime (), and nanosleep () functions are defined to truncate specified 

43055 time values down to the resolution supported by the implementation. Values are truncated 

43056 when set because this appears to be existing practice, and it does not seem reasonable to require 

43057 an error in this case. Note that this is symmetric with the truncation that occurs when reading 

43058 the time via clock_gettime( ) or timer_gettime () at a time that is not an integral multiple of the 

43059 clock or timer resolution. 

43060 This volume of IEEE Std. 1003.1-200x defines functions that allow an application to determine 

43061 the implementation-supported resolution for the clocks and requires an implementation to 

43062 document the resolution supported for timers and nanosleep () if they differ from the supported 

43063 clock resolution. This is more of a procurement issue than a runtime application issue. 

43064 FUTURE DIRECTIONS 

43065 None. 
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SEE ALSO 

clock_getres(), timer_create(), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

<time.h> 

CHANGE HISTORY 

First released in Issue 5. Included for alignment with the POSIX Realtime Extension. 

Issue 6 

The timer_getoverrun (), timer_gettime(), and timer_settime () functions are marked as part of the 
_POSIX_TIMERS option. 

The [ENOSYS] error condition has been removed as stubs need not be provided if an 
implementation does not support the _POSIX_TIMERS option. 

The [EINVAL] error condition is updated to include the following: "and the it_value member of 
that structure did not specify zero seconds and nanoseconds." 

The DESCRIPTION for timer_get overrun () is updated to clarify that "If no expiration signal has 
been delivered for the timer, or if the Realtime Signals Extension is not supported, the return 
value of timer_getoverrun () is unspecified". 
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43081 NAME 

43082 times — get process and waited-for child process times 

43083 SYNOPSIS 

43084 #include <sys/times . h> 

43085 clock_t times (struct tms * buffer) ; 

43086 DESCRIPTION 

43087 The times() function shall fill the tms structure pointed to by buffer with time-accounting 

43088 information. The structure tms is defined in <sys/times.h>. 

43089 All times are measured in terms of the number of clock ticks used. 

43090 The times of a terminated child process are included in the tms_cutime and tms_cstime elements 

43091 of the parent when ivait () or waitpid () returns the process ID of this terminated child. If a child 

43092 process has not waited for its children, their times shall not be included in its times. 

43093 • The tms_utime structure member is the CPU time charged for the execution of user 

43094 instructions of the calling process. 

43095 • The tms_s time structure member is the CPU time charged for execution by the system on 

43096 behalf of the calling process. 

43097 • The tmsjeutime structure member is the sum of the tms_utime and tms_cutime times of the 

43098 child processes. 

43099 • The tms_cstime structure member is the sum of the tms_stime and tms_cstime times of the child 

43100 processes. 

43101 RETURN VALUE 

43102 Upon successful completion, times () shall return the elapsed real time, in clock ticks, since an 

43103 arbitrary point in the past (for example, system start-up time). This point does not change from 

43104 one invocation of times() within the process to another. The return value may overflow the 

43105 possible range of type clock_t. If times () fails, (clock_t)-l shall be returned and errno set to 

43106 indicate the error. 

43107 ERRORS 

43108 No errors are defined. 

43109 EXAMPLES 

43110 Timing a Database Lookup 

43111 The following example defines two functions, start_clock( ) and end_clock( ), that are used to time 

43112 a lookup. It also defines variables of type clock_t and tms to measure the duration of 

43113 transactions. The start_clock() function saves the beginning times given by the times () function. 

43114 The end_clock( ) function gets the ending times and prints the difference between the two times. 

43115 #include <sys/times . h> 

43116 #include <stdio.h> 

43117 

43118 void start_clock (void) ; 

43119 void end_clock (char *msg) ; 

43120 

43121 static clock_t st_time; 

43122 static clock_t en_time; 

43123 static struct tms st_cpu; 

43124 static struct tms en_cpu; 


System Interfaces, Issue 6 


1419 



timesO 


System Interfaces 


43125 

43126 

43127 

43128 

43129 

43130 

43131 

43132 

43133 

43134 

43135 

43136 

43137 

43138 

43139 

43140 

43141 

43142 

43143 

43144 

43145 

43146 

43147 

43148 

43149 

43150 

43151 

43152 

43153 

43154 

43155 

43156 

43157 

43158 

43159 

43160 

43161 

43162 

43163 

43164 

43165 

43166 

43167 


void 

start_clock () 

{ 

st_time = times (&st_cpu); 

} 


void 

end__clock (char *msg) 

{ 

en_time = times (&en_cpu); 
printf (msg); 

printf ("Real Time: %ld. User Time %ld. System Time %ld\n", 
en_time - st_time, 

en_cpu.tms_utime - st_cpu.tms_utime, 
en_cpu.tms_stime - st_cpu.tms_stime); 

} 

APPLICATION USAGE 

Applications should use sysco ;i/(_SC_CLF<_TCI<) to determine the number of clock ticks per 
second as it may vary from system to system. 

RATIONALE 

The accuracy of the times reported is intentionally left unspecified to allow implementations 
flexibility in design, from uniprocessor to multiprocessor networks. 

The inclusion of times of child processes is recursive, so that a parent process may collect the 
total times of all of its descendants. But the times of a child are only added to those of its parent 
when its parent successfully waits on the child. Thus, it is not guaranteed that a parent process 
can always see the total times of all its descendants; see also the discussion of the term realtime in 
alarm (). 

If the type clock_t is defined to be a signed 32-bit integer, it overflows in somewhat more than a 
year if there are 60 clock ticks per second, or less than a year if there are 100. There are individual 
systems that run continuously for longer than that. This volume of IEEE Std. 1003.1-200x permits 
an implementation to make the reference point for the returned value be the start-up time of the I 
process, rather than system start-up time. I 

The term charge in this context has nothing to do with billing for services. The operating system 
accounts for time used in this way. That information must be correct, regardless of how that 
information is used. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

exec, fork(), sysconf(), time(), wait (), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <sys/times.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 
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43168 Issue 4 

43169 

43170 

43171 


The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

• All references to the constant CLK_TCK are removed. 

• The RETURN VALUE section is updated to indicate that (clock_t)-l is returned on error. 
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43172 NAME 

43173 timezone — difference from UTC and local standard time 

43174 SYNOPSIS 

43175 #include <time.h> 

43176 xsi extern long int timezone; 

43177 

43178 DESCRIPTION 

43179 Refer to tzset (). 
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43180 

43181 

43182 

43183 

43184 

43185 

43186 

43187 

43188 

43189 

43190 

43191 

43192 

43193 

43194 

43195 

43196 

43197 

43198 

43199 

43200 

43201 

43202 

43203 

43204 

43205 

43206 

43207 

43208 

43209 

43210 

43211 

43212 

43213 

43214 

43215 

43216 

43217 

43218 

43219 


NAME 

tmpfile — create a temporary file 

SYNOPSIS 

#include <stdio.h> 

FILE *tmpfile(void) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The tmpfile () function shall create a temporary file and open a corresponding stream. The file is 
automatically deleted when all references to the file are closed. The file is opened as inf open {) 
for update (ic+). 

cx The largest value that can be represented correctly in an object of type off_t is established as the 

offset maximum in the open file description. 

In some implementations, a permanent file may be left behind if the process calling tmpfile () is 
killed while it is processing a call to tmpfile (). 

An error message may be written to standard error if the stream cannot be opened. 

RETURN VALUE 

Upon successful completion, tmpfile () shall return a pointer to the stream of the file that is 
cx created. Otherwise, it shall return a null pointer and set errno to indicate the error. 

ERRORS 

The tmpfile () function shall fail if: 
cx [EINTR] A signal was caught during tmpfile(). 

cx [EMFILE] {OPEN_MAX} file descriptors are currently open in the calling process. 

cx [ENFILE] The maximum allowable number of files is currently open in the system. 

cx [ENOSPC] The directory or file system which would contain the new file cannot be 

expanded. 

cx [EOVERFLOW] The file is a regular file and the size of the file cannot be represented correctly 

in an object of type off_t. 

The tmpfile () function may fail if: 

cx [EMFILE] [FOPEN_MAX[ streams are currently open in the calling process, 

cx [ENOMEM] Insufficient storage space is available. 

EXAMPLES 

Creating a Temporary File 

The following example creates a temporary file for update, and returns a pointer to a stream for 
the created file in the fp variable. 

#include <stdio.h> 

FILE *fp; 

fp = tmpfile () ; 
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43220 APPLICATION USAGE 

43221 None. 

43222 RATIONALE 

43223 None. 

43224 FUTURE DIRECTIONS 

43225 None. 

43226 SEE ALSO 

43227 fopen(), tmpnami ), nnlink(), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

43228 <stdio.h> 

43229 CHANGE HISTORY 

43230 First released in Issue 1. 

43231 Derived from Issue 1 of the SVID. 

43232 Issue 4 

43233 The argument list is explicitly defined as void. 

43234 The [EINTR] error is moved to the "fails" part of the ERRORS section; [EMFILE], [ENFILE], and 

43235 [ENOSPC] are no longer marked as extensions; [EACCES], [ENOTDIR], and [EROFS] are 

43236 removed; and the [EMFILE] error in the "may fail" part is marked as an extension. 

43237 Issue 5 

43238 Large File Summit extensions are added. 

43239 The last two paragraphs of the DESCRIPTION were included as APPLICATION USAGE notes 

43240 in previous issues. 

43241 Issue 6 

43242 Extensions beyond the ISO C standard are now marked. 

43243 The following new requirements on POSIX implementations derive from alignment with the 

43244 Single UNIX Specification: 

43245 • In the DESCRIPTION, text is added to indicate setting of the offset maximum in the open file 

43246 description. This change is to support large files. 

43247 • In the ERRORS section, the [EOVERFLOW] condition is added. This change is to support 

43248 large files. 

43249 • The [EMFILE] optional error condition is added. 
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43250 NAME 

43251 tmpnam — create a name for a temporary file 

43252 SYNOPSIS 

43253 #include <stdio.h> 

43254 char *tmpnam(char * s) ; 

43255 DESCRIPTION 

43256 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

43257 conflict between the requirements described here and the ISO C standard is unintentional. This I 

43258 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

43259 The tmpnam () function shall generate a string that is a valid file name and that is not the same as 

43260 the name of an existing file. 

43261 The tmpnam ( ) function generates a different string each time it is called from the same process, 

43262 up to {TMP_MAX} times. If it is called more than {TMP_MAX} times, the behavior is 

43263 implementation-dependent. 

43264 The implementation shall behave as if no function defined in this volume of 

43265 IEEE Std. 1003.1-200x calls tmpnam (). 

43266 cx If the application uses any of the functions guaranteed to be available if either 

43267 _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS is defined, the application shall I 

43268 ensure that the tmpnam () function is called with a non-NULL parameter. I 

43269 RETURN VALUE 

43270 Upon successful completion, tmpnam () shall return a pointer to a string. 

43271 If the argument s is a null pointer, tmpnam () shall leave its result in an internal static object and 

43272 return a pointer to that object. Subsequent calls to tmpnam () may modify the same object. If the 

43273 argument s is not a null pointer, it is presumed to point to an array of at least |L_tmpnam} chars; 

43274 tmpnam () writes its result in that array and returns the argument as its value. 

43275 ERRORS 

43276 No errors are defined. 

43277 EXAMPLES 

43278 Generating a File Name 

43279 The following example generates a unique file name and stores it in the array pointed to by ptr. 

43280 #include <stdio.h> 

43281 

43282 char filename [L_tmpnam+1 ] ; 

43283 char *ptr; 

43284 ptr = tmpnam (filename); 

43285 APPLICATION USAGE 

43286 This function only creates file names. It is the application's responsibility to create and remove 

43287 the files. 

43288 Between the time a path name is created and the file is opened, it is possible for some other 

43289 process to create a file with the same name. Applications may find tmpfile( ) more useful. 
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43290 RATIONALE 

43291 None. 

43292 FUTURE DIRECTIONS 

43293 None. 

43294 SEE ALSO 

43295 fopen(), open(), tempnam(), tmpfile(), unlink(), the System Interface Definitions volume of 

43296 IEEE Std. 1003.1-200x, <stdio.h> 

43297 CHANGE HISTORY 

43298 First released in Issue 1. 

43299 Derived from Issue 1 of the SVID. 

43300 Issue 5 

43301 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 

43302 Issue 6 

43303 Extensions beyond the ISO C standard are now marked. 

43304 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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43305 NAME 

43306 toascii — translate integer to a 7-bit ASCII character 

43307 SYNOPSIS 

43308 xsi #include <ctype.h> 

43309 int toascii (int c) ; 

43310 

43311 DESCRIPTION 

43312 The toascii () function shall convert its argument into a 7-bit ASCII character. 

43313 RETURN VALUE 

43314 The toascii () function shall return the value (c &0x7f). 

43315 ERRORS 

43316 No errors are returned. 

43317 EXAMPLES 

43318 None. 

43319 APPLICATION USAGE 

43320 None. 

43321 RATIONALE 

43322 None. 

43323 FUTURE DIRECTIONS 

43324 None. 

43325 SEE ALSO 

43326 isascii (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <ctype.h> 

43327 CHANGE HISTORY 

43328 First released in Issue 1. 

43329 Derived from Issue 1 of the SVID. 
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43330 NAME 

43331 tolower — transliterate uppercase characters to lowercase 

43332 SYNOPSIS 

43333 #include <ctype.h> 

43334 int tolower (int c) ; 

43335 DESCRIPTION 

43336 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

43337 conflict between the requirements described here and the ISO C standard is unintentional. This I 

43338 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

43339 The tolozver() function has as a domain a type int, the value of which is representable as an 

43340 unsigned char or the value of EOF. If the argument has any other value, the behavior is 

43341 undefined. If the argument of tolower() represents an uppercase letter, and there exists a 

43342 cx corresponding lowercase letter (as defined by character type information in the program locale 

43343 category LC_CTYPE), the result is the corresponding lowercase letter. All other arguments in the 

43344 domain are returned unchanged. 

43345 RETURN VALUE 

43346 Upon successful completion, tolower () shall return the lowercase letter corresponding to the I 

43347 argument passed; otherwise, it shall return the argument unchanged. 

43348 ERRORS 

43349 No errors are defined. 

43350 EXAMPLES 

43351 None. 

43352 APPLICATION USAGE 

43353 None. 

43354 RATIONALE 

43355 None. 

43356 FUTURE DIRECTIONS 

43357 None. 

43358 SEE ALSO 

43359 setlocale(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <ctype.h>, the I 

43360 System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale I 

43361 CHANGE HISTORY 

43362 First released in Issue 1. 

43363 Derived from Issue 1 of the SVID. 

43364 Issue 4 

43365 Reference to "shift information" is replaced by "character type information". 

43366 The RETURN VALUE section is added. 

43367 Issue 6 

43368 Extensions beyond the ISO C standard are now marked. 
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43369 NAME 

43370 toupper — transliterate lowercase characters to uppercase 

43371 SYNOPSIS 

43372 #include <ctype.h> 

43373 int toupper (int c) ; 

43374 DESCRIPTION 

43375 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

43376 conflict between the requirements described here and the ISO C standard is unintentional. This I 

43377 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

43378 The tonpper() function has as a domain a type int, the value of which is representable as an 

43379 unsigned char or the value of EOF. If the argument has any other value, the behavior is 

43380 undefined. If the argument of toupperO represents a lowercase letter, and there exists a 

43381 cx corresponding uppercase letter (as defined by character type information in the program locale 

43382 category LC_CTYPE), the result is the corresponding uppercase letter. All other arguments in the 

43383 domain are returned unchanged. 

43384 RETURN VALUE 

43385 Upon successful completion, toupperO shall return the uppercase letter corresponding to the I 

43386 argument passed. 

43387 ERRORS 

43388 No errors are defined. 

43389 EXAMPLES 

43390 None. 

43391 APPLICATION USAGE 

43392 None. 

43393 RATIONALE 

43394 None. 

43395 FUTURE DIRECTIONS 

43396 None. 

43397 SEE ALSO 

43398 setlocale (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <ctype.h>, the I 

43399 System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale I 

43400 CHANGE HISTORY 

43401 First released in Issue 1. 

43402 Derived from Issue 1 of the SVID. 

43403 Issue 4 

43404 Reference to "shift information" is replaced by "character type information". 

43405 The RETURN VALUE section is added. 

43406 Issue 6 

43407 Extensions beyond the ISO C standard are now marked. 
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43408 NAME 

43409 towctrans — character transliteration 

43410 SYNOPSIS 

43411 #include <wctype.h> 

43412 wint_t towctrans (wint_t wc, wctrans_t desc) ; 

43413 DESCRIPTION 

43414 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

43415 conflict between the requirements described here and the ISO C standard is unintentional. This I 

43416 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

43417 The tozvctrans () function transliterates the wide-character code wc using the mapping described 

43418 by desc. The current setting of the LC_CTYPE category should be the same as during the call to 

43419 cx zvctrans( ) that returned the value desc. If the value of desc is invalid (that is, not obtained by a 

43420 call to zvctrans{) or desc is invalidated by a subsequent call to setlocale() that has affected 

43421 category LC_CTYPE), the result is unspecified. 

43422 An application wishing to check for error situations should set errno to 0 before calling 

43423 tozvctrans (). If errno is non-zero on return, an error has occurred. 

43424 RETURN VALUE 

43425 If successful, the tozvctrans () function shall return the mapped value of zvc using the mapping 

43426 described by desc. Otherwise, it shall return roc unchanged. 

43427 ERRORS 

43428 The tozvctrans () function may fail if: 

43429 cx [EINVAL] desc contains an invalid transliteration descriptor. 

43430 EXAMPLES 

43431 None. 

43432 APPLICATION USAGE 

43433 The strings "tolower" and "toupper" are reserved for the standard mapping names. In the 

43434 table below, the functions in the left column are equivalent to the functions in the right column. 

43435 towlower ( wc) towctrans ( wc, wctrans ("tolower") ) 

43436 towupper ( wc) towctrans ( wc, wctrans ("toupper") ) 

43437 RATIONALE 

43438 None. 

43439 FUTURE DIRECTIONS 

43440 None. 

43441 SEE ALSO 

43442 tozvlozver(), tozvnpper{), zvctrans(), the System Interface Definitions volume of 

43443 IEEE Std. 1003.1-200x, <wctype.h> 

43444 CHANGE HISTORY 

43445 First released in Issue 5. 

43446 Derived from ISO/IEC 9899:1990/Amendment 1:1995 (E). 

43447 Issue 6 

43448 Extensions beyond the ISO C standard are now marked. 
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43449 NAME 

43450 towlower — transliterate uppercase wide-character code to lowercase 

43451 SYNOPSIS 

43452 #include <wctype.h> 

43453 wint_t towlower (wint_t wc) ; 

43454 DESCRIPTION 

43455 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

43456 conflict between the requirements described here and the ISO C standard is unintentional. This I 

43457 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

43458 The tozvlozver( ) function has as a domain a type wint_t, the value of which the application shall I 

43459 ensure is a character representable as a wchar_t, and a wide-character code corresponding to a I 

43460 valid character in the current locale or the value of WEOF. If the argument has any other value, I 

43461 the behavior is undefined. If the argument of tozvlozver( ) represents an uppercase wide-character 

43462 code, and there exists a corresponding lowercase wide-character code (as defined by character 

43463 type information in the program locale category LC_CTYPE), the result is the corresponding 

43464 lowercase wide-character code. All other arguments in the domain are returned unchanged. 

43465 RETURN VALUE 

43466 Upon successful completion, tozvlozver() shall return the lowercase letter corresponding to the I 

43467 argument passed; otherwise, it shall return the argument unchanged. 

43468 ERRORS 

43469 No errors are defined. 

43470 EXAMPLES 

43471 None. 

43472 APPLICATION USAGE 

43473 None. 

43474 RATIONALE 

43475 None. 

43476 FUTURE DIRECTIONS 

43477 None. 

43478 SEE ALSO 

43479 setlocale(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <wctype.h>, 

43480 <wchar.h>, the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale I 

43481 CHANGE HISTORY 

43482 First released in Issue 4. 

43483 Issue 5 

43484 The following change has been made in this issue for alignment with 

43485 ISO/IEC 9899:1990/Amendment 1:1995 (E): 

43486 • The SYNOPSIS has been changed to indicate that this function and associated data types are 

43487 now made visible by inclusion of the header <wctype.h> rather than <wchar.h>. 

43488 Issue 6 I 

43489 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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43490 NAME 

43491 towupper — transliterate lowercase wide-character code to uppercase 

43492 SYNOPSIS 

43493 tinclude <wctype.h> 

43494 wint_t towupper (wint_t wc) ; 

43495 DESCRIPTION 

43496 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

43497 conflict between the requirements described here and the ISO C standard is unintentional. This 

43498 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. 

43499 The tozvupper( ) function has as a domain a type wint_t, the value of which the application shall 

43500 ensure is a character representable as a wchar_t, and a wide-character code corresponding to a 

43501 valid character in the current locale or the value of WEOF. If the argument has any other value, 

43502 the behavior is undefined. If the argument of tozvupper( ) represents a lowercase wide-character 

43503 code, and there exists a corresponding uppercase wide-character code (as defined by character 

43504 type information in the program locale category LC_CTYPE), the result is the corresponding 

43505 uppercase wide-character code. All other arguments in the domain are returned unchanged. 

43506 RETURN VALUE 

43507 Upon successful completion, towupper () shall return the uppercase letter corresponding to the 

43508 argument passed. Otherwise, it shall return the argument unchanged. 

43509 ERRORS 

43510 No errors are defined. 

43511 EXAMPLES 

43512 None. 

43513 APPLICATION USAGE 

43514 None. 

43515 RATIONALE 

43516 None. 

43517 FUTURE DIRECTIONS 

43518 None. 

43519 SEE ALSO 

43520 setlocale(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <wctype.h>, 

43521 <wchar.h>, the System Interface Definitions volume of IEEE Std. 1003.1-200x, Chapter 7, Locale 

43522 CHANGE HISTORY 

43523 First released in Issue 4. 

43524 Issue 5 

43525 The following change has been made in this issue for alignment with 

43526 ISO/IEC 9899:1990/Amendment 1:1995 (E): 

43527 • The SYNOPSIS has been changed to indicate that this function and associated data types are 

43528 now made visible by inclusion of the header <wctype.h> rather than <wchar.h>. 

43529 Issue 6 

43530 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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43531 NAME 

43532 truncate — truncate a file to a specified length 

43533 SYNOPSIS 

43534 xsi #include <unistd.h> 

43535 int truncate (const char *path, off_t length) ; 

43536 

43537 DESCRIPTION 

43538 The truncate () function shall cause the regular file named by path to have a size of length bytes. 

43539 If the file previously was larger than length, the extra data is discarded. If it was previously 

43540 shorter than length, it is unspecified whether the file is changed or its size increased. If the file is 

43541 extended, the extended area appears as if it were zero-filled. 

43542 The application shall ensure that the process has write permission for the file. I 

43543 If the request would cause the file size to exceed the soft file size limit for the process, the 

43544 request shall fail and the implementation shall generate the SIGXFSZ signal for the process. 

43545 This function shall not modify the file offset for any open file descriptions associated with the I 

43546 file. Upon successful completion, if the file size is changed, this function shall mark for update I 

43547 the stjctime and s t_mtime fields of the file, and if the file is a regular file, the S_ISUID and 

43548 S_ISGID bits of the file mode may be cleared. 

43549 RETURN VALUE 

43550 Upon successful completion, tnmcate( ) shall return 0. Otherwise, -1 shall be returned, and err no 

43551 set to indicate the error. 

43552 ERRORS 

43553 The tmncate( ) function shall fail if: 

43554 [EINTR] A signal was caught during execution. 

43555 [EINVAL] The length argument was less than 0. 

43556 [EFBIG] or [EINVAL] 

43557 The length argument was greater than the maximum file size. 

43558 [EIO] An I/O error occurred while reading from or writing to a file system. 

43559 [EACCES] A component of the path prefix denies search permission, or write permission 

43560 is denied on the file. 

43561 [EISDIR] The named file is a directory. 

43562 [ELOOP] Too many symbolic links were encountered in resolving path. 

43563 [ENAMETOOLONG] 

43564 The length of the specified path name exceeds {PATH_MAX} bytes, or the 

43565 length of a component of the path name exceeds [NAME_MAX[ bytes while 

43566 _POSIX_NO_TRUNC is in effect. 

43567 [ENOENT] A component of path does not name an existing file or path is an empty string. 

43568 [ENOTDIR] A component of the path prefix of path is not a directory. 

43569 [EROFS] The named file resides on a read-only file system. 

43570 The tmncate( ) function may fail if: 
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43571 [ENAMETOOLONG] 

43572 Path name resolution of a symbolic link produced an intermediate result 

43573 whose length exceeds |PATH_MAX}. 

43574 EXAMPLES 

43575 None. 

43576 APPLICATION USAGE 

43577 None. 

43578 RATIONALE 

43579 None. 

43580 FUTURE DIRECTIONS 

43581 None. 

43582 SEE ALSO 

43583 open(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

43584 CHANGE HISTORY 

43585 First released in Issue 4, Version 2. 

43586 Issue 5 

43587 Moved from X/OPEN UNIX extension to BASE. 

43588 Large File Summit extensions are added. 

43589 Issue 6 

43590 This reference page is split out from th e/truncate( ) reference page. 

43591 The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. This 

43592 is since behavior may vary from one file system to another. 

43593 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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43594 NAME 

43595 tdelete, tfind, tsearch, twalk — manage a binary search tree 

43596 SYNOPSIS 

43597 xsi #include <search.h> 

43598 

43599 

43600 

43601 

43602 

43603 

43604 

43605 

43606 

43607 DESCRIPTION 

43608 The tdelete(), tfind(), tsearch(), and tivalk() functions manipulate binary search trees. 

43609 Comparisons are made with a user-supplied routine, the address of which is passed as the 

43610 compar argument. This routine is called with two arguments, the pointers to the elements being I 

43611 compared. The application shall ensure that the user-supplied routine returns an integer less I 

43612 than, equal to, or greater than 0, according to whether the first argument is to be considered less I 

43613 than, equal to, or greater than the second argument. The comparison function need not compare I 

43614 every byte, so arbitrary data may be contained in the elements in addition to the values being I 

43615 compared. I 

43616 The tsearch () function is used to build and access the tree. The key argument is a pointer to an 

43617 element to be accessed or stored. If there is a node in the tree whose element is equal to the value 

43618 pointed to by key, a pointer to this found node is returned. Otherwise, the value pointed to by 

43619 key is inserted (that is, a new node is created and the value of key is copied to this node), and a 

43620 pointer to this node returned. Only pointers are copied, so the application shall ensure that the I 

43621 calling routine stores the data. The rooty argument points to a variable that points to the root I 

43622 node of the tree. A null pointer value for the variable pointed to by rooty denotes an empty tree; 

43623 in this case, the variable shall be set to point to the node which shall be at the root of the new 

43624 tree. 

43625 Like tsearch (), tfind () shall search for a node in the tree, returning a pointer to it if found. 

43626 However, if it is not found, tfind () shall return a null pointer. The arguments for tfind () are the 

43627 same as for tsearch (). 

43628 The tdelete( ) function deletes a node from a binary search tree. The arguments are the same as 

43629 for tsearch (). The variable pointed to by rooty shall be changed if the deleted node was the root 

43630 of the tree. The tdelete( ) function returns a pointer to the parent of the deleted node, or a null 

43631 pointer if the node is not found. 

43632 The twalk () function traverses a binary search tree. The root argument is a pointer to the root 

43633 node of the tree to be traversed. (Any node in a tree may be used as the root for a walk below 

43634 that node.) The argument action is the name of a routine to be invoked at each node. This routine 

43635 is, in turn, called with three arguments. The first argument is the address of the node being 

43636 visited. The structure pointed to by this argument is unspecified and shall not be modified by I 

43637 the application, but it is guaranteed that a pointer-to-node can be converted to pointer-to- I 

43638 pointer-to-element to access the element stored in the node. The second argument is a value I 

43639 from an enumeration data type: I 

43640 typedef enum { preorder, postorder, endorder, leaf } VISIT; 


void *tdelete(const void *key, void ** rootp, 

int (*compar) (const void *, const void *)); 
void *tfind(const void *key, void *const *rootp, 
int(* compar) (const void *, const void *)); 
void *tsearch(const void *key, void ** rootp, 

int ( *compar) (const void *, const void *)); 
void twalk(const void *root, 

void (*action) (const void *, VISIT, int)); 
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43641 (defined in <search.h>), depending on whether this is the first, second, or third time that the 

43642 node is visited (during a depth-first, left-to-right traversal of the tree), or whether the node is a 

43643 leaf. The third argument is the level of the node in the tree, with the root being level 0. 

43644 If the calling function alters the pointer to the root, the result is undefined. 

43645 RETURN VALUE 

43646 If the node is found, both tsearch () and tfind () shall return a pointer to it. If not, tfind () shall 

43647 return a null pointer, and tsearch () shall return a pointer to the inserted item. 

43648 A null pointer shall be returned by tsearch () if there is not enough space available to create a new 

43649 node. 

43650 A null pointer shall be returned by tdelete(), tfind (), and tsearch () if rootp is a null pointer on 

43651 entry. 

43652 The tdelete( ) function shall return a pointer to the parent of the deleted node, or a null pointer if 

43653 the node is not found. 

43654 The tzvalk( ) function shall return no value. 


43655 ERRORS 

43656 No errors are defined. 


43657 EXAMPLES 

43658 

43659 

43660 


43661 

43662 

43663 


The following code reads in strings and stores structures containing a pointer to each string and 
a count of its length. It then walks the tree, printing out the stored strings and their lengths in 
alphabetical order. 

#include <search.h> 

#include <string.h> 

#include <stdio.h> 


43664 #define STRSZ 10000 

43665 #define NODSZ 500 


43666 

43667 

43668 

43669 


struct node { /* Pointers to these are stored in the tree. */ 

char *string; 

int length; 

}; 


43670 

43671 

43672 


char string_space[STRSZ ] ; 
struct node nodes[NODSZ ] ; 
void *root = NULL; 


/* Space to store strings. */ 
/* Nodes to store. */ 

/* This points to the root. */ 


43673 

43674 

43675 

43676 

43677 

43678 


int main(int argc, char *argv[]) 

{ 

char *strptr = string_space; 

struct node *nodeptr = nodes; 

void print_node(const void *, VISIT, int); 

int i = 0, node_compare(const void *, const void *); 


43679 

43680 

43681 

43682 

43683 

43684 

43685 


while (gets(strptr) != NULL && i++ < NODSZ) { 

/* Set node. */ 

nodeptr—>string = strptr; 

nodeptr—>length = strlen (strptr); 

/* Put node into the tree. */ 

(void) tsearch((void *)nodeptr, (void **)&root, 
node_compare) ; 
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43686 /* Adjust pointers, so we do not overwrite tree. */ 

43687 strptr += nodeptr—>length + 1; 

43688 nodeptr+ + ; 

43689 } 

43690 twalk (root, print_node); 

43691 return 0; 

43692 } 

43693 / * 

43694 * This routine compares two nodes, based on an 

43695 * alphabetical ordering of the string field. 

43696 * / 

43697 int 

43698 node_compare (const void *nodel, const void *node2) 

43699 { 

43700 return strcmp (( (const struct node *) nodel) — >string, 

43701 ((const struct node *) node2) —>string) ; 

43702 } 

43703 / * 

43704 * This routine prints out a node, the second time 

43705 * twalk encounters it or if it is a leaf. 

43706 * / 

43707 void 

43708 print_node (const void *ptr, VISIT order, int level) 

43709 { 

43710 const struct node *p = * (const struct node **) ptr; 

43711 if (order == postorder | | order == leaf) { 

43712 (void) printf ("string = %s, length = %d\n", 

43713 p->string, p->length) ; 

43714 } 

43715 } 

43716 APPLICATION USAGE 

43717 The root argument to tzvalk() is one level of indirection less than the rootp arguments to tdelete( ) 

43718 and tsearch (). 

43719 There are two nomenclatures used to refer to the order in which tree nodes are visited. The 

43720 tsearch() function uses preorder, postorder, and endorder to refer respectively to visiting a node 

43721 before any of its children, after its left child and before its right, and after both its children. The 

43722 alternative nomenclature uses preorder, inorder, and postorder to refer to the same visits, which 

43723 could result in some confusion over the meaning of postorder. 

43724 RATIONALE 

43725 None. 

43726 FUTURE DIRECTIONS 

43727 None. 

43728 SEE ALSO 

43729 hcreate( ), IsearchO, the System Interface Definitions volume of IEEE Std. 1003.1-200x, <search.h> 
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43730 CHANGE HISTORY 

43731 First released in Issue 1. 

43732 Derived from Issue 1 of the SVID. 

43733 Issue 4 

43734 The type of argument key is changed from char* to const void*. 

43735 The function return value is changed from char* to void*. 

43736 Arguments to compar are formally defined. 

43737 The type of argument rootp is changed from char** to void** for the tsearch () function. 

43738 The type of argument rootp is changed from char** to void*const* for the tfind () function. 

43739 The type of argument root is changed from char* to const void*, and the argument list to action is 

43740 formally defined for the tivalk( ) function. 

43741 Various minor wording changes are made in the DESCRIPTION to improve clarity and 

43742 accuracy. In particular, additional notes are added about constraints on the first argument to 

43743 twalk(). 

43744 The sample code in the EXAMPLES section is updated to use ISO C standard syntax. Also the 

43745 definition of the root and argv items is changed. 

43746 The paragraph in the APPLICATION USAGE section about casts is removed. 

43747 Issue 5 

43748 The last paragraph of the DESCRIPTION was included as an APPLICATION USAGE note in 

43749 previous issues. 

43750 Issue 6 

43751 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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43752 NAME 

43753 ttyname, ttyname_r — find path name of a terminal 

43754 SYNOPSIS 

43755 tinclude <unistd.h> 

43756 char *ttyname (int fildes) ; 

43757 TSF int ttyname_r (int fildes, char *name, size_t namesize) ; 

43758 

43759 DESCRIPTION 

43760 The ttyname () function shall return a pointer to a string containing a null-terminated path name 

43761 of the terminal associated with file descriptor fildes. The return value may point to static data 

43762 whose content is overwritten by each call. 

43763 The ttyname () function need not be reentrant. A function that is not required to be reentrant is 

43764 not required to be thread-safe. 

43765 tsf The ttyname_r( ) function stores the null-terminated path name of the terminal associated with 

43766 the file descriptor fildes in the character array referenced by name. The array is namesize 

43767 characters long and should have space for the name and the terminating null character. The 

43768 maximum length of the terminal name is {TTY_NAME_MAX}. 

43769 RETURN VALUE 

43770 Upon successful completion, ttyname () shall return a pointer to a string. Otherwise, a null 

43771 man pointer shall be returned and errno set to indicate the error. 

43772 tsf If successful, the ttyname_r( ) function shall return zero. Otherwise, an error number shall be 

43773 returned to indicate the error. 

43774 ERRORS 

43775 The ttyname () function may fail if: 

43776 man [EBADF] Th e fildes argument is not a valid file descriptor. 

43777 man [ENOTTY] Th e fildes argument does not refer to a terminal device. 

43778 The ttyname_r( ) function may fail if: 

43779 tsf [EBADF] Th e fildes argument is not a valid file descriptor. 

43780 tsf [ENOTTY] Th e fildes argument does not refer to a tty. 

43781 Notes to Reviewers 

43782 This section with side shading will not appear in the final copy. - Ed. 

43783 Dl, XSH, ERN 397 points out an inconsistency for the [ERANGE] error 

43784 condition below and suggests this be changed to [E2BIG]. 

43785 tsf [ERANGE] The value of namesize is smaller than the length of the string to be returned 

43786 including the terminating null character. 
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43787 EXAMPLES 

43788 None. 

43789 APPLICATION USAGE 

43790 None. 

43791 RATIONALE 

43792 The term terminal is used instead of the historical term terminal device in order to avoid a 

43793 reference to an undefined term. 

43794 The thread-safe version places the terminal name in a user-supplied buffer and returns a non- 

43795 zero value if it fails. The non-thread-safe version may return the name in a static data area that 

43796 may be overwritten by each call. 

43797 FUTURE DIRECTIONS 

43798 None. 

43799 SEE ALSO 

43800 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

43801 CHANGE HISTORY 

43802 First released in Issue 1. 

43803 Derived from Issue 1 of the SVID. 

43804 Issue 4 

43805 The <unistd.h> header is added to the SYNOPSIS. 

43806 The statement indicating that errno is set on error in the RETURN VALUE section, and the errors 

43807 [EBADF] and [ENOTTY], are marked as extensions. 

43808 Issue 5 

43809 The ttyname_r( ) function is included for alignment with the POSIX Threads Extension. 

43810 A note indicating that the ttyname() function need not be reentrant is added to the 

43811 DESCRIPTION. 

43812 Issue 6 

43813 The ttyname_r{) function is marked as part of the _POSIX_THREAD_SAFE_FUNCTIONS 

43814 option. 

43815 The following new requirements on POSIX implementations derive from alignment with the 

43816 Single UNIX Specification: 

43817 • The statement that errno is set on error is added. 

43818 • The [EBADF] and [ENOTTY] optional error conditions are added. 
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43819 NAME 

43820 twalk — traverse a binary search tree 

43821 SYNOPSIS 

43822 xsi #include <search.h> 

43823 void twalk (const void *root, 

43824 void (* action) (const void *, VISIT, int )); 

43825 

43826 DESCRIPTION 

43827 Refer to tsearch (). 


System Interfaces, Issue 6 


1441 




tzname 


System Interfaces 


43828 NAME 

43829 tzname — timezone strings 

43830 SYNOPSIS 

43831 tinclude <time.h> 

43832 extern char *tzname[]; 

43833 DESCRIPTION 

43834 Refer to tzset (). 
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43835 NAME 

43836 daylight, timezone, tzname, tzset — set timezone conversion information 

43837 SYNOPSIS 

43838 tinclude <time.h> 

43839 xsi extern int daylight; 

43840 extern long int timezone; 

43841 extern char *tzname [2] ; 

43842 void tzset (void) ; 

43843 DESCRIPTION 

43844 The tzset () function uses the value of the environment variable TZ to set time conversion 

43845 information used by ctime(), localtime(), mktime(), and strftime(). If TZ is absent from the 

43846 environment, implementation-dependent default timezone information is used. 

43847 The tzset () function shall set the external variable tzname as follows: 

43848 tzname [0] = "std"; 

43849 tzname [1] = "dst"; 

43850 where std and dst are as described in the System Interface Definitions volume of I 

43851 IEEE Std. 1003.1-200x, Chapter 8, Environment Variables. I 

43852 xsi The tzset() function also shall set the external variable daylight to 0 if Daylight Savings Time 

43853 conversions should never be applied for the timezone in use; otherwise, non-zero. The external 

43854 variable timezone shall be set to the difference, in seconds, between Coordinated Universal Time 

43855 (UTC) and local standard time. 

43856 RETURN VALUE 

43857 The tzset () function shall return no value. 

43858 ERRORS 

43859 No errors are defined. 

43860 EXAMPLES 

43861 Example TZ variables and their timezone differences are given in the table below: 

43862 


43863 

TZ 

timezone 

43864 

EST 

5*60*60 

43865 

GMT 

0*60*60 

43866 

JST 

-9*60*60 

43867 

MET 

-1*60*60 

43868 

MST 

7*60*60 

43869 

PST 

8*60*60 


43870 APPLICATION USAGE 

43871 None. 

43872 RATIONALE 

43873 None. 

43874 FUTURE DIRECTIONS 

43875 None. 
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43876 

43877 

43878 

43879 

43880 

43881 

43882 

43883 

43884 

43885 

43886 

43887 


SEE ALSO 

ctime(), localtime (), mktime (), strftime(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <time.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The reference to timezone in the SYNOPSIS section is marked as an extension. 

The type of timezone is expanded to extern long int. 

The <time.h> header is added to the SYNOPSIS section. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The argument list is explicitly defined as void. 
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43888 NAME 

43889 ualarm — set the interval timer 

43890 SYNOPSIS 

43891 xsi #include <unistd.h> 

43892 useconds_t ualarm(useconds_t useconds, useconds_t interval) ; 

43893 

43894 DESCRIPTION 

43895 The ualarm () function shall cause the SIGALRM signal to be generated for the calling process 

43896 after the number of realtime microseconds specified by the useconds argument has elapsed. 

43897 When the interval argument is non-zero, repeated timeout notification occurs with a period in 

43898 microseconds specified by the interval argument. If the notification signal, SIGALRM, is not 

43899 caught or ignored, the calling process is terminated. 

43900 Implementations may place limitations on the granularity of timer values. For each interval 

43901 timer, if the requested timer value requires a finer granularity than the implementation supports, 

43902 the actual timer value shall be rounded up to the next supported value. 

43903 Interactions between ualarm () and any of the following are unspecified: 

43904 alarm () 

43905 nanosleep () 

43906 setitimeri ) 

43907 timer_create () 

43908 timer_delete () 

43909 timer_getoverrun () 

43910 timer_gettime{) 

43911 timer_settime () 

43912 sleep () 

43913 RETURN VALUE 

43914 The ualarm () function shall return the number of microseconds remaining from the previous 

43915 ualarm () call. If no timeouts are pending or if ualarm () has not previously been called, ualarm () 

43916 shall return 0. 

43917 ERRORS 

43918 No errors are defined. 

43919 EXAMPLES 

43920 None. 

43921 APPLICATION USAGE 

43922 Applications are recommended to use nanosleep ( ) if the _POSIX_TIMER option is supported, or 

43923 setitimeri ), timer_create(), timer_delete(), timer_getoverrun (), timer_gettime (), or timer_settime() 

43924 instead of this function. 

43925 RATIONALE 

43926 None. 

43927 FUTURE DIRECTIONS 

43928 None. 

43929 SEE ALSO 

43930 alarm (), nanosleep (), setitimeri ), sleep (), timer_create(), timer_delete{), timer_getoverrun(), the 

43931 System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 
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43932 

43933 

43934 

43935 


CHANGE HISTORY 

First released in Issue 4, Version 2. 

Issue 5 

Moved from X/OPEN UNIX extension to BASE. 
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43936 NAME 

43937 ulimit — get and set process limits 

43938 SYNOPSIS 

43939 xsi #include <ulimit.h> 

43940 long int ulimit (int cmd, . . . ) ; 

43941 


43942 DESCRIPTION 

43943 The ulimit () function provides for control over process limits. The process limits that can be 

43944 controlled by this function include the maximum size of a single file that can be written (this is 

43945 equivalent to using setrlimit() with RLIMIT_FSIZE). The cmd values, defined in <ulimit.h> 

43946 include: 


43947 

43948 

43949 

43950 

43951 


UL_GETFSIZE Return the file size limit (RLIMIT_FSIZE) of the process. The limit is in units 
of 512-byte blocks and is inherited by child processes. Files of any size can be 
read. The return value shall be the integer part of the soft file size limit 
divided by 512. If the result cannot be represented as a long int, the result is 
unspecified. 


43952 

43953 

43954 

43955 

43956 

43957 


UL_SETFSIZE Set the file size limit for output operations of the process to the value of the 
second argument, taken as a long int. Any process may decrease its own 
limit, but only a process with appropriate privileges may increase the limit. 
The new file size limit shall be returned. The file size limit is set to the 
specified value multiplied by 512. If the result would overflow an rlim_t, the 
actual value set is unspecified. 


43958 The ulimit () function shall not change the setting of errno if successful. 


43959 As all return values are permissible in a successful situation, an application wishing to check for 

43960 error situations should set errno to 0, then call ulimit (), and, if it returns -1, check to see if errno is 

43961 non-zero. 


43962 RETURN VALUE 

43963 Upon successful completion, ulimit () shall return the value of the requested limit. Otherwise, -1 

43964 shall be returned and errno set to indicate the error. 


43965 ERRORS 

43966 The ulimit () function shall fail and the limit shall be unchanged if: 

43967 [EINVAL] The cmd argument is not valid. 

43968 [EPERM] A process not having appropriate privileges attempts to increase its file size 

43969 limit. 

43970 EXAMPLES 

43971 None. 

43972 APPLICATION USAGE 

43973 None. 

43974 RATIONALE 

43975 None. 

43976 FUTURE DIRECTIONS 

43977 None. 
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43978 

43979 

43980 

43981 

43982 

43983 

43984 

43985 

43986 

43987 

43988 

43989 

43990 

43991 

43992 

43993 

43994 


SEE ALSO 

getrlimit (), setrlimit (), write (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, 

<ulimit.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The use of long is replaced by long int in the SYNOPSIS and the DESCRIPTION sections. 

Issue 4, Version 2 

In the DESCRIPTION, the discussion of UL_GETFSIZE and UL_SETFSIZE is revised generally to 
distinguish between the soft and the hard file size limit of the process. For UL_GETFSIZE, the 
return value is defined more precisely. For UL_SETFSIZE, the effect on both file size limits is 
specified, as is the effect if the result would overflow an rlim_t. 

Issue 5 

In the description of UL_SETFSIZE, the text is corrected to refer to rlim_t rather than the 
spurious rlimit_t 

The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 
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43995 

43996 

43997 

43998 

43999 

44000 

44001 

44002 

44003 

44004 

44005 

44006 

44007 

44008 

44009 

44010 

44011 

44012 

44013 

44014 

44015 

44016 

44017 

44018 

44019 

44020 

44021 

44022 

44023 

44024 

44025 

44026 

44027 

44028 

44029 

44030 

44031 

44032 

44033 

44034 

44035 

44036 

44037 


NAME 

umask — set and get file mode creation mask 

SYNOPSIS 

#include <sys/stat.h> 
mode_t umask(mode_t cmask) ; 

DESCRIPTION 

The umask() function shall set the process' file mode creation mask to cmask and return the 
previous value of the mask. Only the file permission bits of cmask (see <sys/stat.h>) are used; the 
meaning of the other bits is implementation-dependent. 

The process' file mode creation mask is used during open(), creat (), mkdir{ ), and mkfifo( ) to turn 
off permission bits in the mode argument supplied. Bit positions that are set in cmask are cleared 
in the mode of the created file. 

RETURN VALUE 

The file permission bits in the value returned by umask () shall be the previous value of the file 
mode creation mask. The state of any other bits in that value is unspecified, except that a 
subsequent call to nmask( ) with the returned value as cmask shall leave the state of the mask the 
same as its state before the first call, including any unspecified use of those bits. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

Unsigned argument and return types for umask() were proposed. The return type and the 
argument were both changed to mode_t. 

Historical implementations have made use of additional bits in cmask for their implementation- 
dependent purposes. The addition of the text that the meaning of other bits of the field is 
implementation-dependent permits these implementations to conform to this volume of 
IEEE Std. 1003.1-200x. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

creat(), mkdir{), mkfifo(), open(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <sys/stat.h>, <sys/types.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 
XSI-conformant systems. 

The RETURN VALUE section is expanded, in line with the ISO POSIX-1 standard, to describe 
the situation with regard to additional bits in the file mode creation mask. 
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44038 

44039 

44040 

44041 

44042 

44043 

44044 


Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 
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44045 NAME 

44046 uname — get name of current system 

44047 SYNOPSIS 

44048 tinclude <sys/utsname.h> 

44049 int uname (struct utsname * name) } 

44050 DESCRIPTION 

44051 The uname () function shall store information identifying the current system in the structure 

44052 pointed to by name. 

44053 The uname{) function uses the utsname structure defined in <sys/utsname.h>. 

44054 The uname( ) function returns a string naming the current system in the character array sysname. 

44055 Similarly, nodename contains the name that the system is known by on a communications 

44056 network. The arrays release and version further identify the operating system. The array machine 

44057 contains a name that identifies the hardware that the system is running on. 

44058 The format of each member is implementation-dependent. 

44059 RETURN VALUE 

44060 Upon successful completion, a non-negative value shall be returned. Otherwise, -1 shall be 

44061 returned and errno set to indicate the error. 

44062 ERRORS 

44063 No errors are defined. 

44064 EXAMPLES 

44065 None. 

44066 APPLICATION USAGE 

44067 The inclusion of the nodename member in this structure does not imply that it is sufficient 

44068 information for interfacing to communications networks. 

44069 RATIONALE 

44070 The values of the structure members are not constrained to have any relation to the version of 

44071 this volume of IEEE Std. 1003.1-200x implemented in the operating system. An application 

44072 should instead depend on _POSIX_VERSION and related constants defined in <unistd.h>. 

44073 This volume of IEEE Std. 1003.1-200x does not define the sizes of the members of the structure 

44074 and permits them to be of different sizes, although most implementations define them all to be 

44075 the same size: eight bytes plus one byte for the string terminator. That size for nodename is not 

44076 enough for use with many networks. 

44077 The uname() function is specific to System III, System V, and related implementations, and it 

44078 does not exist in Version 7 or 4.3 BSD. The values it returns are set at system compile time in 

44079 those historical implementations. 

44080 4.3 BSD has ge t host name ( ) and gethostid(), which return a symbolic name and a numeric value, 

44081 respectively. There are related sethostname{) and sethostid() functions that are used to set the 

44082 values the other two functions return. The length of the host name is limited to 31 characters in 

44083 most implementations and the host ID is a 32-bit integer. 

44084 FUTURE DIRECTIONS 

44085 None. 
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44086 

44087 

44088 

44089 

44090 

44091 

44092 

44093 

44094 

44095 

44096 


SEE ALSO 

The System Interface Definitions volume of IEEE Std. 1003.1-200x, <sys/utsname.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 

Issue 4 

The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

• The DESCRIPTION is changed to indicate that the format of members in the utsname 
structure is implementation-dependent. 

• The RETURN VALUE section is updated to indicate that -1 is returned and errno set to 
indicate an error. 
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44097 NAME 

44098 ungetc — push byte back into input stream 

44099 SYNOPSIS 

44100 tinclude <stdio.h> 

44101 int ungetc (int c, FILE * stream); 

44102 DESCRIPTION 

44103 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

44104 conflict between the requirements described here and the ISO C standard is unintentional. This I 

44105 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

44106 The ungetc () function shall push the byte specified by c (converted to an unsigned char) back 

44107 onto the input stream pointed to by stream. The pushed-back bytes shall be returned by 

44108 subsequent reads on that stream in the reverse order of their pushing. A successful intervening 

44109 call (with the stream pointed to by stream) to a file-positioning function (fseek (), fsetpos (), or 

44110 rewind ()) discards any pushed-back bytes for the stream. The external storage corresponding to 

44111 the stream is unchanged. 

44112 One byte of push-back is guaranteed. If ungetc() is called too many times on the same stream 

44113 without an intervening read or file-positioning operation on that stream, the operation may fail. 

44114 If the value of c equals that of the macro EOF, the operation fails and the input stream is 

44115 unchanged. 

44116 A successful call to ungetc() shall clear the end-of-file indicator for the stream. The value of the 

44117 file-position indicator for the stream after reading or discarding all pushed-back bytes shall be 

44118 the same as it was before the bytes were pushed back. The file-position indicator is decremented 

44119 by each successful call to ungetc( ); if its value was 0 before a call, its value is indeterminate after 

44120 the call. 

44121 RETURN VALUE 

44122 Upon successful completion, ungetc () shall return the byte pushed back after conversion. 

44123 Otherwise, it shall return EOF. 

44124 ERRORS 

44125 No errors are defined. 

44126 EXAMPLES 

44127 None. 

44128 APPLICATION USAGE 

44129 None. 

44130 RATIONALE 

44131 None. 

44132 FUTURE DIRECTIONS 

44133 None. 

44134 SEE ALSO 

44135 fseek(), getc(), fsetpos (), read(), rewind (), setbuf(), the System Interface Definitions volume of 

44136 IEEE Std. 1003.1-200x, <stdio.h> 

44137 CHANGE HISTORY 

44138 First released in Issue 1. 

44139 Derived from Issue 1 of the SVID. 
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44140 

44141 

44142 

44143 

44144 

44145 

44146 

44147 

44148 


Issue 4 

The DESCRIPTION is changed to make it clear that nngetc() manipulates bytes rather than 
(possibly multi-byte) characters. 

The APPLICATION USAGE section is removed. 

The following changes are incorporated for alignment with the ISO C standard: 

• Th efsetpos () function is added to the list of file-positioning functions in the DESCRIPTION. 

• Also, this issue states that the file-position indicator is decremented by each successful call to 
ungetc(), although note that XSI-conformant systems do not distinguish between text and 
binary streams. Previous issues state that the disposition of this indicator is unspecified. 
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44149 

44150 

44151 

44152 

44153 

44154 

44155 

44156 

44157 

44158 

44159 

44160 

44161 

44162 

44163 

44164 

44165 

44166 

44167 

44168 

44169 

44170 

44171 

44172 

44173 

44174 

44175 

44176 

44177 

44178 

44179 

44180 

44181 

44182 

44183 

44184 

44185 

44186 

44187 

44188 

44189 


NAME 

ungetwc — push wide-character code back into input stream 

SYNOPSIS 

#include <stdio.h> 

#include <wchar.h> 

wint_t ungetwc(wint_t wc, FILE * stream); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The ungetzvc() function shall push the character corresponding to the wide-character code 
specified by wc back onto the input stream pointed to by stream. The pushed-back characters 
shall be returned by subsequent reads on that stream in the reverse order of their pushing. A 
successful intervening call (with the stream pointed to by stream) to a file-positioning function 
(/seek (), fsetpos (), or rewind ()) discards any pushed-back characters for the stream. The external 
storage corresponding to the stream is unchanged. 

One character of push-back is guaranteed. If ungetwc () is called too many times on the same 
stream without an intervening read or file-positioning operation on that stream, the operation 
may fail. 

If the value of wc equals that of the macro WEOF, the operation fails and the input stream is 
unchanged. 

A successful call to ungetwc () shall clear the end-of-file indicator for the stream. The value of the 
file-position indicator for the stream after reading or discarding all pushed-back characters shall 
be the same as it was before the characters were pushed back. The file-position indicator is 
decremented (by one or more) by each successful call to ungetwc{); if its value was 0 before a 
call, its value is indeterminate after the call. 

RETURN VALUE 

Upon successful completion, ungetwc{) shall return the wide-character code corresponding to 
the pushed-back character. Otherwise, it shall return WEOF. 

ERRORS 

The ungetzvc( ) function may fail if: 

[EILSEQ] An invalid character sequence is detected, or a wide-character code does not 

correspond to a valid character. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 
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44190 

44191 

44192 

44193 

44194 

44195 

44196 

44197 


SEE ALSO 

fseek(), fsetpos(), read(), rewind(), setbuf(), the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <stdio.h>, <wchar.h> 

CHANGE HISTORY 

First released in Issue 4. 

Derived from the MSE working draft. 

Issue 5 

The Optional Header (OH) marking is removed from <stdio.h>. 
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44198 NAME 

44199 unlink — remove a directory entry 

44200 SYNOPSIS 

44201 tinclude <unistd.h> 


44202 int unlink (const char *path) ; 


44203 DESCRIPTION 


44204 MAN 

44205 

44206 

44207 


The unlink() function shall remove a link to a file. If path names a symbolic link, unlinkO 
removes the symbolic link named by path and does not affect any file or directory named by the 
contents of the symbolic link. Otherwise, unlinkO removes the link named by the path name 
pointed to by path and decrements the link count of the file referenced by the link. 


44208 

44209 

44210 

44211 


When the file's link count becomes 0 and no process has the file open, the space occupied by the 
file shall be freed and the file shall no longer be accessible. If one or more processes have the file 
open when the last link is removed, the link shall be removed before unlinkO returns, but the 
removal of the file contents shall be postponed until all references to the file are closed. 


44212 The application shall ensure that the path argument does not name a directory unless the process I 

44213 has appropriate privileges and the implementation supports using unlink () on directories. I 


44214 Upon successful completion, unlink() shall mark for update the st_ctime and stjntime fields of 

44215 the parent directory. Also, if the file's link count is not 0, the stjctime field of the file shall be 

44216 marked for update. 


44217 RETURN VALUE 

44218 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno set to 

44219 indicate the error. If -1 is returned, the named file shall not be changed. 


44220 ERRORS 

44221 The unlink () function shall fail and shall not unlink the file if: 


44222 

[EACCES] 

Search permission is 

44223 


permission is denied 

44224 


removed. 


denied for a component of the path prefix, or write 
on the directory containing the directory entry to be 


44225 

44226 

44227 


[EBUSY] The file named by the path argument cannot be unlinked because it is being 

used by the system or another process and the implementation considers this 
an error. 


44228 MAN [ELOOP] 

44229 


A loop exists in symbolic links encountered during resolution of the path I 
argument. I 


44230 

44231 

44232 

44233 


[ENAMETOOLONG] 

The length of the path argument exceeds |PATH_MAX} or a path name 
component is longer than |NAME_MAX} while _POSIX_NO_TRUNC is in 
effect. 


44234 

44235 

44236 

44237 

44238 


[ENOENT] A component of path does not name an existing file or path is an empty string. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EPERM] The file named by path is a directory, and either the calling process does not 

have appropriate privileges, or the implementation prohibits using unlinkO 
on directories. 


44239 xsi [EPERM] or [EACCES] 

44240 The S_ISVTX flag is set on the directory containing the file referred to by the 

44241 path argument and the caller is not the file owner, nor is the caller the 
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44242 

44243 

44244 

44245 

44246 

44247 

44248 

44249 

44250 

44251 

44252 

44253 

44254 

44255 

44256 

44257 

44258 

44259 

44260 

44261 

44262 

44263 

44264 

44265 

44266 

44267 

44268 

44269 

44270 

44271 

44272 

44273 

44274 

44275 

44276 

44277 

44278 

44279 

44280 

44281 

44282 

44283 


directory owner, nor does the caller have appropriate privileges. 

[EROFS] The directory entry to be unlinked is part of a read-only file system. 

The unlink () function may fail and not unlink the file if: 

xsi [EBUSY] The file named by path is a named STREAM. I 

[ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during I 

resolution of the path argument. I 

man [ENAMETOOLONG1 


man |E f X f Bb Y J the entry to be unlinked is the last directory entry to a pure procedure (shared 

text) file that is being executed. 

EXAMPLES 

Removing a Link to a File 

The following example shows how to remove a link to a file named /home/cnd/modl by 
removing the entry named /modules/passl. 

((include <unistd.h> 

char *path = "/modules/passl"; 
int status; 

status = unlink (path); 

Checking for an Error 

The following example fragment creates a temporary password lock file named LOCKFILE, 
which is defined as /etc/ptmp, and gets a file descriptor for it. If the file cannot be opened for 
writing, unlink( ) is used to remove the link between the file descriptor and LOCKFILE. 

((include <sys/types.h> 

((include <stdio.h> 

((include <fcntl.h> 

((include <errno.h> 

((include <unistd.h> 

((include <sys/stat.h> 

#define LOCKFILE "/etc/ptmp" 

int pfd; /* Integer for file descriptor returned by open call. */ 

FILE *fpfd; /* File pointer for use in putpwentO . */ 

/* Open password Lock file. If it exists, this is an error. */ 
if ((pfd = open (LOCKFILE, 0_WR0NLY| 0_CREAT | 0_EXCL, S_IRUSR 
| S_IWUSR | S_IRGRP | S_IROTH)) == -1) { 

fprintf (stderr, "Cannot open /etc/ptmp. Try again later.\n"); 
exit (1); 

} 

/* Lock file created, proceed with fdopen of lock file so that 
putpwentO can be used. 
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44284 * / 

44285 if ((fpfd = fdopen (pfd, "w")) == NULL) { 

44286 close (pfd) ; 

44287 unlink (LOCKFILE) ; 

44288 exit (1); 

44289 } 

44290 Replacing Files 

44291 The following example fragment uses unlink() to discard links to files, so that they can be 

44292 replaced with new versions of the files. The first call remove the link to LOCKFILE if an error 

44293 occurs. Successive calls remove the links to SAVEFILE and PASSWDFILE so that new links can 

44294 be created, then removes the link to LOCKFILE when it is no longer needed. 

44295 #include <sys/types .h> 

44296 #include <stdio.h> 

44297 #include <fcntl.h> 

44298 #include <errno.h> 

44299 #include <unistd.h> 

44300 #include <sys/stat.h> 

44301 #define LOCKFILE "/etc/ptmp" 

44302 #define PASSWDFILE "/etc/passwd" 

44303 #define SAVEFILE "/etc/opasswd" 

44304 

44305 /* If no change was made, assume error and leave passwd unchanged. */ 

44306 if ( ! valid_change) { 

44307 fprintf (stderr, "Could not change password for user %s\n", user); 

44308 unlink (LOCKFILE); 

44309 exit (1); 

44310 } 

44311 /* Change permissions on new password file. */ 

44312 chmod (LOCKFILE, S_IRUSR I S_IRGRP | S_IROTH) ; 

44313 /* Remove saved password file. */ 

44314 unlink (SAVEFILE); 

44315 /* Save current password file. */ 

44316 link (PASSWDFILE, SAVEFILE); 

44317 /* Remove current password file. */ 

44318 unlink (PASSWDFILE); 

44319 /* Save new password file as current password file. */ 

44320 link (LOCKFILE, PASSWDFILE) ; 

44321 /* Remove lock file. */ 

44322 unlink (LOCKFILE) ; 

44323 exit (0); 

44324 APPLICATION USAGE 

44325 Applications should use rmdir( ) to remove a directory. 
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44326 

44327 

44328 

44329 

44330 

44331 

44332 

44333 

44334 

44335 

44336 

44337 

44338 

44339 

44340 

44341 

44342 

44343 

44344 

44345 

44346 

44347 

44348 

44349 

44350 

44351 

44352 

44353 

44354 

44355 

44356 

44357 

44358 

44359 

44360 

44361 

44362 

44363 

44364 

44365 

44366 


RATIONALE 

Unlinking a directory is restricted to the superuser in many historical implementations for 
reasons given in link () (see also rename ()). 

The meaning of [EBUSY] in historical implementations is "mount point busy". Since this volume 
of IEEE Std. 1003.1-200x does not cover the system administration concepts of mounting and 
unmounting, the description of the error was changed to "resource busy". (This meaning is used 
by some device drivers when a second process tries to open an exclusive use device.) The 
wording is also intended to allow implementations to refuse to remove a directory if it is the 
root or current working directory of any process. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

close(), link(), remove (), rmdir (), the System Interface Definitions volume of 

IEEE Std. 1003.1-200x, <unistd.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The <unistd.h> header is added to the SYNOPSIS section. 

The error [ETXTBSY] is marked as an extension. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The type of argument path is changed from char 51 ' to const char*. 

The following change is incorporated for alignment with the FIPS requirements: 

• In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 
name component is larger that |NAME_MAX[ is now defined as mandatory and marked as 
an extension. 

Issue 4, Version 2 

The entry is updated for X/OPEN UNIX conformance as follows: 

• In the DESCRIPTION, the effect is specified if path specifies a symbolic link. 

• In the ERRORS section, [ELOOP] is added to indicate that too many symbolic links were 
encountered during path name resolution 

• In the ERRORS section, [EPERM] or [EACCES] are added to indicate a permission check 
failure when operating on directories with S_ISVTX set. 

• In the ERRORS section, a second [ENAMETOOLONG] condition is defined that may report 
excessive length of an intermediate result of path name resolution of a symbolic link. 

Issue 5 

The [EBUSY] error is added to the "may fail" part of the ERRORS section. 

Issue 6 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 
This is since behavior may vary from one file system to another. 
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44369 

44370 

44371 

44372 

44373 

44374 

44375 


The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the DESCRIPTION, the effect is specified if path specifies a symbolic link. 

• The [ELOOP] mandatory error condition is added. 

• A second [ENAMETOOLONG] is added as an optional error condition. 

• The [ETXTBSY] optional error condition is added. 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• The [ELOOP] optional error condition is added. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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44376 NAME 

44377 unlockpt — unlock a pseudo-terminal master/slave pair 

44378 SYNOPSIS 

44379 xsi #include <stdlib.h> 

44380 int unlockpt (int fildes) ; 

44381 

44382 DESCRIPTION 

44383 The unlockpt () function shall unlock the slave pseudo-terminal device associated with the 

44384 master to which fildes refers. 

44385 Portable applications shall ensure that they call unlockpt () before opening the slave side of a I 

44386 pseudo-terminal device. 

44387 RETURN VALUE 

44388 Upon successful completion, unlockpt () shall return 0. Otherwise, it shall return -1 and set errno 

44389 to indicate the error. 

44390 ERRORS 

44391 The unlockpt () function may fail if: 

44392 [EBADF] The fildes argument is not a file descriptor open for 

44393 [EINVAL] The fildes argument is not associated with a master 

44394 EXAMPLES 

44395 None. 

44396 APPLICATION USAGE 

44397 None. 

44398 RATIONALE 

44399 None. 

44400 FUTURE DIRECTIONS 

44401 None. 

44402 SEE ALSO 

44403 grantpt(), open(), ptsname(), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

44404 <stdlib.h> 

44405 CHANGE HISTORY 

44406 First released in Issue 4, Version 2. 

44407 Issue 5 

44408 Moved from X/OPEN UNIX extension to BASE. 

44409 Issue 6 

44410 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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44411 

44412 

44413 

44414 

44415 

44416 

44417 

44418 

44419 

44420 

44421 

44422 

44423 

44424 

44425 

44426 

44427 

44428 

44429 

44430 

44431 

44432 

44433 

44434 

44435 

44436 

44437 

44438 

44439 

44440 

44441 

44442 

44443 

44444 

44445 


NAME 

unsetenv — remove environment variable 

SYNOPSIS 

#include <stdlib.h> 

int unsetenv(const char * name ); 

DESCRIPTION 

The unsetenv () function removes an environment variable from the environment of the calling 
process. The name argument points to a string, which is the name of the variable to be removed. 
The named argument shall not contain an ' =' character. If the named variable does not exist in 
the current environment, the environment is unchanged and the function is considered to have 
completed successfully. 

If the application modifies environ or the pointers to which it points, the behavior of unsetenv () is 
undefined. The unsetenv( ) function shall update the list of pointers to which environ points. 

The unsetenv( ) function need not be reentrant. A function that is not required to be reentrant is 
not required to be thread-safe. 

RETURN VALUE 

Upon successful completion, zero shall be returned. Otherwise, -1 shall be returned, errno set to 
indicate the error, and the environment shall be unchanged. 

ERRORS 

The unsetenv( ) function shall fail if: 

[EINVAL] The name argument is a null pointer, points to an empty string, or points to a 

string containing an ' =' character. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

Refer to the RATIONALE section in setenv (). 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

getenv(), setenv(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdlib.h>, 
<sys/types.h>, <unistd.h> 

CHANGE HISTORY 

First released in Issue 6. Derived from the IEEE P1003.1a draft standard. 
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44446 NAME 

44447 usleep — suspend execution for an interval 

44448 SYNOPSIS 

44449 xsi #include <unistd.h> 

44450 int usleep (useconds_t useconds) ; 

44451 

44452 DESCRIPTION 

44453 The usleep () function shall cause the calling thread to be suspended from execution until either 

44454 the number of realtime microseconds specified by the argument useconds has elapsed or a signal 

44455 is delivered to the calling thread and its action is to invoke a signal-catching function or to 

44456 terminate the process. The suspension time may be longer than requested due to the scheduling 

44457 of other activity by the system. 

44458 The application shall ensure that the useconds argument is less than 1,000,000. If the value of I 

44459 useconds is 0, then the call has no effect. 

44460 If a SIGALRM signal is generated for the calling process during execution of usleep () and if the 

44461 SIGALRM signal is being ignored or blocked from delivery, it is unspecified whether usleep () 

44462 returns when the SIGALRM signal is scheduled. If the signal is being blocked, it is also 

44463 unspecified whether it remains pending after usleep () returns or it is discarded. 

44464 If a SIGALRM signal is generated for the calling process during execution of usleep (), except as a 

44465 result of a prior call to alarm (), and if the SIGALRM signal is not being ignored or blocked from 

44466 delivery, it is unspecified whether that signal has any effect other than causing usleep () to return. 

44467 If a signal-catching function interrupts usleep () and examines or changes either the time a 

44468 SIGALRM is scheduled to be generated, the action associated with the SIGALRM signal, or 

44469 whether the SIGALRM signal is blocked from delivery, the results are unspecified. 

44470 If a signal-catching function interrupts usleep () and calls siglongjmp() or longjmp() to restore an 

44471 environment saved prior to the usleep () call, the action associated with the SIGALRM signal and 

44472 the time at which a SIGALRM signal is scheduled to be generated are unspecified. It is also 

44473 unspecified whether the SIGALRM signal is blocked, unless the process' signal mask is restored 

44474 as part of the environment. 

44475 Implementations may place limitations on the granularity of timer values. For each interval 

44476 timer, if the requested timer value requires a finer granularity than the implementation supports, 

44477 the actual timer value shall be rounded up to the next supported value. 

44478 Interactions between usleep () and any of the following are unspecified: 

44479 nanosleep () 

44480 setitimer () 

44481 timer_create( ) 

44482 timer_delete( ) 

44483 timer_getoverrun () 

44484 timer_get time () 

44485 timer_settime( ) 

44486 ualarm () 

44487 sleep () 
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44488 RETURN VALUE 

44489 Upon successful completion, asleep {) shall return 0; otherwise, it shall return -1 and set errno to I 

44490 indicate the error. 

44491 ERRORS 

44492 The asleep () function may fail if: 

44493 [EINVAL] The time interval specified 1,000,000 or more microseconds. 

44494 EXAMPLES 

44495 None. 

44496 APPLICATION USAGE 

44497 Applications are recommended to use nanosleep () if the _POSIX_TIMER option is supported, or 

44498 setitimer (), timer_create{), timer_delete(), timer_getoverrun (), timer_gettime{ ), or timer_settime {) 

44499 instead of this function. 

44500 RATIONALE 

44501 None. 

44502 FUTURE DIRECTIONS 

44503 None. 

44504 SEE ALSO 

44505 alarm (), getitimer( ), nanosleep (), sigaction (), sleep (), timer_create( ), timer_delete( ), 

44506 timer_getoverrun (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <unistd.h> 

44507 CHANGE HISTORY 

44508 First released in Issue 4, Version 2. 

44509 Issue 5 

44510 Moved from X/OPEN UNIX extension to BASE. 

44511 The DESCRIPTION is changed to indicate that timers are now thread-based rather than 

44512 process-based. I 

44513 Issue 6 I 

44514 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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44515 NAME 

44516 utime — set file access and modification times 

44517 SYNOPSIS 

44518 #include <utime.h> 


44519 int utime (const char *path, const struct utimbuf *times); 

44520 DESCRIPTION 

44521 The utime ( ) function shall set the access and modification times of the file named by the path 

44522 argument. 

44523 If times is a null pointer, the access and modification times of the file are set to the current time. I 

44524 The application shall ensure that the effective user ID of the process matches the owner of the I 

44525 file, or the process has write permission to the file or has appropriate privileges, to use utime ( ) in I 

44526 this manner. 

44527 If times is not a null pointer, times is interpreted as a pointer to a utimbuf structure and the 

44528 access and modification times are set to the values contained in the designated structure. Only a 

44529 process with effective user ID equal to the user ID of the file or a process with appropriate 

44530 privileges may use utime ( ) this way. 

44531 The utimbuf structure is defined by the header <utime.h>. The times in the structure utimbuf 

44532 are measured in seconds since the Epoch. 

44533 Upon successful completion, utime ( ) shall mark the time of the last file status change, st_ctime, 

44534 to be updated; see <sys/stat.h>. 

44535 RETURN VALUE 

44536 Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno shall 

44537 be set to indicate the error, and the file times shall not be affected. 


44538 ERRORS 

44539 The utime () function shall fail if: 


44540 

44541 

44542 

44543 


[EACCES] Search permission is denied by a component of the path prefix; or the times 

argument is a null pointer and the effective user ID of the process does not 
match the owner of the file, the process does not have write permission for the 
file, and the process does not have appropriate privileges. 


44544 MAN [ELOOP] 

44545 


A loop exists in symbolic links encountered during resolution of the path 
argument. 


44546 

44547 

44548 

44549 


[ENAMETOOLONG] 

The length of the path argument exceeds |PATH_MAX} or a path name 
component is longer than {NAME_MAX} while _POSIX_NO_TRUNC is in 
effect. 


44550 

44551 

44552 

44553 

44554 


[ENOENT] A component of path does not name an existing file or path is an empty string. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EPERM] The times argument is not a null pointer and the calling process' effective user I 

ID does not match the owner of the file and the calling process does not have I 
the appropriate privileges. I 


44555 


[EROFS] 


The file system containing the file is read-only. 


44556 


The utime () function may fail if: 


1466 


Technical Standard (2000) (Draft February 29, 2000) 




System Interfaces 


utime() 


44557 

44558 

44559 

44560 

44561 

44562 

44563 

44564 

44565 

44566 

44567 

44568 

44569 

44570 

44571 

44572 

44573 

44574 

44575 

44576 

44577 

44578 

44579 

44580 

44581 

44582 

44583 

44584 

44585 

44586 

44587 

44588 

44589 

44590 

44591 

44592 

44593 

44594 

44595 

44596 

44597 

44598 

44599 


[ELOOP] More than {SYMLOOP_MAX} symbolic links were encountered during I 

resolution of the path argument. I 

man [ENAMETOOLONG] 

As a result of encountering a symbolic link in resolution of the path argument, I 
the length of the substituted path name string exceeded {PATH_MAX}. I 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

The actime structure member must be present so that an application may set it, even though an 
implementation may ignore it and not change the access time on the file. If an application 
intends to leave one of the times of a file unchanged while changing the other, it should use 
stat () to retrieve the file's st_atime and stjntime parameters, set actime and modtime in the buffer, 
and change one of them before making the utime () call. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

The System Interface Definitions volume of IEEE Std. 1003.1-200x, <sys/types.h>, <utime.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The <sys/types.h> header is now marked as optional (OH); this header need not be included on 
XSI-conformant systems. 

The following change is incorporated for alignment with the ISO POSIX-1 standard: 

• The type of argument path is changed from char* to const char*, and times is changed from 

struct utimbuf* to const struct utimbuf*. 

The following change is incorporated for alignment with the FIPS requirements: 

• In the ERRORS section, the condition whereby [ENAMETOOLONG] is returned if a path 
name component is larger that ]NAME_MAX] is now defined as mandatory and marked as 
an extension. 

Issue 4, Version 2 

The ERRORS section is updated for X/OPEN UNIX conformance as follows: 

• It states that [ELOOP] is returned if too many symbolic links are encountered during path 
name resolution. 

• A second [ENAMETOOLONG] condition is defined that may report excessive length of an 
intermediate result of path name resolution of a symbolic link. 

Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

• The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 
This is since behavior may vary from one file system to another. 
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44602 

44603 

44604 

44605 

44606 

44607 

44608 

44609 


The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

• The [ELOOP] mandatory error condition is added. 

• A second [ENAMETOOLONG] is added as an optional error condition. 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• The [ELOOP] optional error condition is added. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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44619 
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44621 

44622 
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44634 

44635 

44636 

44637 

44638 
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44641 
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44644 

44645 

44646 

44647 

44648 

44649 

44650 

44651 


NAME 

utimes — set file access and modification times (LEGACY) 

SYNOPSIS 

xsi tinclude <sys/time.h> 

int utimes(const char *path, const struct timeval times[2]); 


DESCRIPTION 

The utimes () function shall set the access and modification times of the file pointed to by the path 
argument to the value of the times argument. The utimes () function allows time specifications 
accurate to the microsecond. 


For utimes(), the times argument is an array of timeval structures. The first array member 
represents the date and time of last access, and the second member represents the date and time 
of last modification. The times in the timeval structure are measured in seconds and 
microseconds since the Epoch, although rounding toward the nearest second may occur. 

If the times argument is a null pointer, the access and modification times of the file shall be set to I 
the current time. The application shall ensure that the effective user ID of the process is the same I 
as the owner of the file, or has write access to the file or appropriate privileges to use this call in I 
this manner. Upon completion, utimesO shall mark the time of the last file status change, I 
stjctime, for update. 

RETURN VALUE 

Upon successful completion, 0 shall be returned. Otherwise, -1 shall be returned and errno shall 
be set to indicate the error, and the file times shall not be affected. 


ERRORS 

The utimes () function shall fail if: 

[EACCES] Search permission is denied by a component of the path prefix; or the times 

argument is a null pointer and the effective user ID of the process does not 
match the owner of the file and write access is denied. 

[ELOOP] Too many symbolic links were encountered in resolving path. 

[ENAMETOOLONG] 

The length of the path argument exceeds |PATH_MAX) or a path name 
component is longer than |NAME_MAX} while _POSIX_NO_TRUNC is in 
effect. 


[ENOENT] A component of path does not name an existing file or path is an empty string. 

[ENOTDIR] A component of the path prefix is not a directory. 

[EPERM] The times argument is not a null pointer and the calling process' effective user 

ID has write access to the file but does not match the owner of the file and the 
calling process does not have the appropriate privileges. 

[EROFS] The file system containing the file is read-only. 

The utimesO function may fail if: 


[ENAMETOOLONG] 

Path name resolution of a symbolic link produced an intermediate result 
whose length exceeds {PATH_MAX[. 
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44652 EXAMPLES 

44653 None. 

44654 APPLICATION USAGE 

44655 For applications portability, the utime( ) function should be used to set file access and 

44656 modification times instead of utimes (). 

44657 RATIONALE 

44658 None. 

44659 FUTURE DIRECTIONS 

44660 This function may be withdrawn in a future version. 

44661 SEE ALSO 

44662 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <sys/time.h> 

44663 CHANGE HISTORY 

44664 First released in Issue 4, Version 2. 

44665 Issue 5 

44666 Moved from X/OPEN UNIX extension to BASE. 

44667 Issue 6 

44668 This function is marked LEGACY. 

44669 The following changes are made for alignment with the ISO POSIX-1:1996 standard: 

44670 • The [ENAMETOOLONG] error is restored as an error dependent on _POSIX_NO_TRUNC. 

44671 This is since behavior may vary from one file system to another. 

44672 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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44673 NAME 

44674 va_arg, va_end, va_start — handle variable argument list 

44675 SYNOPSIS 

44676 tinclude <stdarg.h> 

44677 type va_arg (va_list ap, type); 

44678 void va_end (va_list ap) ; 

44679 void va_start (va_list ap, argN) ; 

44680 DESCRIPTION 

44681 Refer to the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdarg.h>. 
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44682 NAME 

44683 vfork — create new process; share virtual memory 

44684 SYNOPSIS 

44685 xsi #include <unistd.h> 

44686 pid_t vfork (void) ; 

44687 

44688 DESCRIPTION 

44689 The vfork () function has the same effect as fork (), except that the behavior is undefined if the 

44690 process created by vfork () either modifies any data other than a variable of type pid_t used to 

44691 store the return value from vfork (), or returns from the function in which vfork () was called, or 

44692 calls any other function before successfully calling __exit ( ) or one of the exec family of functions. 

44693 RETURN VALUE 

44694 Upon successful completion, vfork ( ) shall return 0 to the child process and return the process ID 

44695 of the child process to the parent process. Otherwise, -1 shall be returned to the parent, no child 

44696 process shall be created, and errno shall be set to indicate the error. 

44697 ERRORS 

44698 The vfork ( ) function shall fail if: 

44699 [EAGAIN] The system-wide limit on the total number of processes under execution 

44700 would be exceeded, or the system-imposed limit on the total number of 

44701 processes under execution by a single user would be exceeded. 

44702 [ENOMEM] There is insufficient swap space for the new process. 

44703 EXAMPLES 

44704 None. 

44705 APPLICATION USAGE 

44706 On some systems, vfork ( ) is the same as fork (). 

44707 The vfork () function differs from fork() only in that the child process can share code and data 

44708 with the calling process (parent process). This speeds cloning activity significantly at a risk to 

44709 the integrity of the parent process if zfork( ) is misused. 

44710 The use of vfork () for any purpose except as a prelude to an immediate call to a function from 

44711 the exec family, or to _exit (), is not advised. 

44712 The vfork () function can be used to create new processes without fully copying the address 

44713 space of the old process. If a forked process is simply going to call exec, the data space copied 

44714 from the parent to the child by fork () is not used. This is particularly inefficient in a paged 

44715 environment, making vfork () particularly useful. Depending upon the size of the parent's data 

44716 space, vfork () can give a significant performance improvement over fork (). 

44717 The vfork () function can normally be used just like fork (). It does not work, however, to return 

44718 while running in the child's context from the caller of vfork () since the eventual return from 

44719 vfork () would then return to a no longer existent stack frame. Care should be taken, also, to call 

44720 _exit() rather than exit() if exec cannot be used, since exit() flushes and closes standard I/O 

44721 channels, thereby damaging the parent process' standard I/O data structures. (Even with fork( ), 

44722 it is wrong to call exit( ), since buffered data would then be flushed twice.) 

44723 If signal handlers are invoked in the child process after vfork (), they must follow the same rules 

44724 as other code in the child process. 
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44725 RATIONALE 

44726 None. 

44727 FUTURE DIRECTIONS 

44728 None. 

44729 SEE ALSO 

44730 exec, exit (), fork (), wait ( ), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

44731 <unistd.h> 

44732 CHANGE HISTORY 

44733 First released in Issue 4, Version 2. 

44734 Issue 5 

44735 Moved from X/OPEN UNIX extension to BASE. 
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NAME 

vfprintf, vprintf, vsnprintf, vsprintf — format output of a stdarg argument list 

SYNOPSIS 

#include <stdarg.h> 

#include <stdio.h> 

int vfprintf(FILE * stream, const char * format, va_list ap) ; 
int vprintf(const char * format , va_list ap) ; 
xsi int vsnprintf(char *s, size_t n, const char * format, va_list ap); 

int vsprintf(char *s, const char * format , va_list ap) ; 

DESCRIPTION 

cx For vfprintf (), vprintf (), and vsprintf (): The functionality described on this reference page is 

aligned with the ISO C standard. Any conflict between the requirements described here and the I 
ISO C standard is unintentional. This volume of IEEE Std. 1003.1-200x defers to the ISO C I 
standard. I 

xsi The vprintf (), vfprintf (), vsnprintf (), and vsprintf () functions shall be the same as printf(), 

xsi fprintf (), snprintfi ), and sprintf( ) respectively, except that instead of being called with a variable 

number of arguments, they are called with an argument list as defined by <stdarg.h>. 

These functions do not invoke the va_end macro. As these functions invoke the va_arg macro, the 
value of ap after the return is indeterminate. 

RETURN VALUE 

Refer to fprintf( ). 

ERRORS 

Refer to fprintf( ). 

EXAMPLES 

None. 

APPLICATION USAGE 

Applications using these functions should call va_end(ap) afterwards to clean up. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

fprintf(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <stdarg.h>, 
<stdio.h> 

CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

The APPLICATION USAGE section is added. 

The FUTURE DIRECTIONS section is removed. 

The following changes are incorporated for alignment with the ISO C standard: 
• These functions are no longer marked as extensions. 
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• The type of argument format is changed from char’'' to const char’''. 


44779 

44780 

44781 


• Reference to the <varargs.h> header in the DESCRIPTION is replaced by <stdarg.h>. The 
last paragraph has also been added to indicate interactions with the va_arg and va_end 
macros. 


44782 Issue 5 

44783 The vsnprintf () function is added. 
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44784 NAME 

44785 vfwprintf, vswprintf, vwprintf — wide-character formatted output of a stdarg argument list 

44786 SYNOPSIS 

44787 #include <stdarg.h> 

44788 #include <stdio.h> 

44789 #include <wchar.h> 

44790 int vfwprintf (FILE * stream, const wchar_t * format , va_list arg) ; 

44791 int vswprintf (wchar_t *s, size_t n, const wchar_t * format, 

44792 va_list arg) ; 

44793 int vwprintf (const wchar_t * format, va_list arg) ; 

44794 DESCRIPTION 

44795 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

44796 conflict between the requirements described here and the ISO C standard is unintentional. This I 

44797 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

44798 The vfwprintf (), vswprintf ’(), and vwprintf () functions shall be the same as fwprintf( ), swprintf( ), 

44799 and wprintf() respectively, except that instead of being called with a variable number of 

44800 arguments, they are called with an argument list as defined by <stdarg.h>. 

44801 These functions do not invoke the va_end macro. However, as these functions do invoke the 

44802 va_arg macro, the value of ap after the return is indeterminate. 

44803 RETURN VALUE 

44804 Ref er to fzvp rintf(). 

44805 ERRORS 

44806 Ref er to fzvp rintf(). 

44807 EXAMPLES 

44808 None. 

44809 APPLICATION USAGE 

44810 Applications using these functions should call va_end(ap) afterwards to clean up. 

44811 RATIONALE 

44812 None. 

44813 FUTURE DIRECTIONS 

44814 None. 

44815 SEE ALSO 

44816 fzvprintfi ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <stdarg.h>, 

44817 <stdio.h>, <wchar.h> 

44818 CHANGE HISTORY 

44819 First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 

44820 (E). I 
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44821 NAME 

44822 vprintf, vsnprintf, vsprintf — format output of a stdarg argument list 

44823 SYNOPSIS 

44824 #include <stdarg.h> 

44825 #include <stdio.h> 

44826 int vprintf (const char * format , va_list ap) ; 

44827 xsi int vsnprintf (char *s, size_t n, const char * format, va_list ap) ; 

44828 int vsprintf (char *s, const char * format, va_list ap) ; 

44829 DESCRIPTION 

44830 Refer to vfprintf (). 
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44831 NAME 

44832 vswprintf, vwprintf — wide-character formatted output of a stdarg argument list 

44833 SYNOPSIS 

44834 #include <stdarg.h> 

44835 #include <stdio.h> 

44836 #include <wchar.h> 

44837 int vswprintf (wchar_t *s, size_t n, const wchar_t * format , 

44838 va_list arg) ; 

44839 int vwprintf (const wchar_t * format, va_list arg) ; 

44840 DESCRIPTION 

44841 Refer to vsivprintf (). 
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NAME 

wait, waitpid — wait for a child process to stop or terminate 

SYNOPSIS 

#include <sys/wait.h> 
pid_t wait(int *stat_loc) ; 

pid_t waitpid(pid_t pid, int *stat_loc, int options) ; 

DESCRIPTION 

The zvait() and zvaitpid() functions allow the calling process to obtain status information 
pertaining to one of its child processes. Various options permit status information to be obtained 
for child processes that have terminated or stopped. If status information is available for two or 
more child processes, the order in which their status is reported is unspecified. 

The wait () function shall suspend execution of the calling thread until status information for one 
of the terminated child processes of the calling process is available, or until delivery of a signal 
whose action is either to execute a signal-catching function or to terminate the process. If more 
than one thread is suspended in wait () or zvaitpid() awaiting termination of the same process, 
exactly one thread shall return the process status at the time of the target process termination. If 
status information is available prior to the call to zuait (), return shall be immediate. 

The zuaitpid () function shall behave identically to zuait { ) if the pid argument is (pid_t)-l and the 
options argument is 0. Otherwise, its behavior shall be modified by the values of the pid and 
options arguments. 

The pid argument specifies a set of child processes for which status is requested. The zuaitpid () I 
function shall only return the status of a child process from this set: 

• If pid is equal to (pid_t)-l, status is requested for any child process. In this respect, zuaitpid () I 
is then equivalent to zuait (). 

• If pid is greater than 0, it specifies the process ID of a single child process for which status is I 

requested. I 

• If pid is 0, status is requested for any child process whose process group ID is equal to that of I 

the calling process. I 

• If pid is less than (pid_t)-l, status is requested for any child process whose process group ID I 

is equal to the absolute value of pid . I 

The options argument is constructed from the bitwise-inclusive OR of zero or more of the 
following flags, defined in the header <sys/wait.h>: 

xsi WCONTINUED The zuaitpid () function shall report the status of any continued child process 

specified by pid whose status has not been reported since it continued from a 
job control stop. 

WNOHANG The zuaitpid () function shall not suspend execution of the calling thread if I 
status is not immediately available for one of the child processes specified by I 
pid. 

WUNTRACED The status of any child processes specified by pid that are stopped, and whose 
status has not yet been reported since they stopped, is shall also be reported to 
the requesting process. 

xsi If the calling process has SA_NOCLDWAIT set or has SIGCHLD set to SIG_IGN, and the 
process has no unwaited-for children that were transformed into zombie processes, the calling 
thread shall block until all of the children of the process containing the calling thread terminate, 
and zuait () and zuaitpid () shall fail and set errno to [ECHILD], 
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If wait() or waitpid() return because the status of a child process is available, these functions 
shall return a value equal to the process ID of the child process. In this case, if the value of the 
argument stat_loc is not a null pointer, information shall be stored in the location pointed to by 
stat_loc . If and only if the status returned is from a terminated child process that returned 0 from 
main() or passed 0 as the status argument to _exit() or exit(), the value stored at the location 
pointed to by stat_loc shall be 0. Regardless of its value, this information may be interpreted 
using the following macros, which are defined in <sys/wait.h> and evaluate to integral 
expressions; the stat_val argument is the integer value pointed to by stat_loc. 

WIFEXITED (s f a t_val ) 

Evaluates to a non-zero value if status was returned for a child process that terminated I 
normally. I 

WEXITSTATUS(sfflf_z;fl/) 

If the value of WIF EX IT E D (s hi t_val ) is non-zero, this macro evaluates to the low-order 8 bits 
of the status argument that the child process passed to _exit( ) or exit( ), or the value the child 
process returned from main(). 

WIFSIGNALED(sfflf_z>fl/) 

Evaluates to non-zero value if status was returned for a child process that terminated due to 
the receipt of a signal that was not caught (see <signal.h>). 

WTERMSIG(sfflf_z;fl/) 

If the value of WIFSIGNALED(sf a t_val ) is non-zero, this macro evaluates to the number of 
the signal that caused the termination of the child process. 

WIFSTOPPED(stef_z;fl/) 

Evaluates to a non-zero value if status was returned for a child process that is currently 
stopped. 

WSTOPSI G(stat_val) 

If the value of WIFSTO PFFD(stat_val) is non-zero, this macro evaluates to the number of the 
signal that caused the child process to stop. 

xsi WIFCONTINUED(sfflf_CYzZ) 

Evaluates to a non-zero value if status was returned for a child process that has continued 
from a job control stop. 

spn It is unspecified whether the status value returned by calls to wait ( ) or zvaitpid() for processes I 
created by posix_spazvn () or posix_spawnp () may indicate a WIFSTOPPED(sfflf_z;fl/) before I 
subsequent calls to wait () or zvaitpid() indicate WIFEXITED(stef_cflZ) as the result of an error I 
detected before the new process image starts executing. I 

It is unspecified whether the status value returned by calls to ivait() or zvaitpid() for processes I 
created by posix_spazvn () or posix_spazvnp () may indicate a WIFSIGNALED(stof_z;fl/) if a signal is I 
sent to the parent's process group after posix_spazvn () or posix_spazvnp () is called. I 

If the information pointed to by stat_loc was stored by a call to zvaitpid() that specified the I 
xsi WUNTRACED flag and did not specify the WCONTINUED flag, exactly one of the macros 
WIFEXITED(*sfaf_/oc), WIFSIGNALED(*sfflfJoc), and WIFSTOPPED(*stofJoc) shall evaluate to 
a non-zero value. 

If the information pointed to by statjoc was stored by a call to zvaitpid() that specified the 
xsi WUNTRACED and WCONTINUED flags, exactly one of the macros WIFEXITED(*stofJoc), 
xsi WIFSIGNALED(*sfflfJoc), WIFSTOPPED(*sfflfJoc), and WIFCONTINUED(*sfflfJoc) shall 
evaluate to a non-zero value. 
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44932 If the information pointed to by stat_loc was stored by a call to zvaitpid () that did not specify the 

44933 xsi WUNTRACED or WCONTINUED flags, or by a call to the zvait() function, exactly one of the 

44934 macros WIF EX IT E D (*s ta t_loc) and WIFSIGNALED(*sfflf_/oc) shall evaluate to a non-zero value. 

44935 If the information pointed to by stat_loc was stored by a call to zvaitpid () that did not specify the 

44936 xsi WUNTRACED flag and specified the WCONTINUED flag,or by a call to the wait{) function, 

44937 xsi exactly one of the macros WIFEXITED(*sfflf_/oc), WIFSIG N A L ED (*s tat Joe), and 

44938 WIFC O NT IN U ED (*s ta t_loc) shall evaluate to a non-zero value. 

44939 If _POSIX_REALTIME_SIGNALS is defined, and the implementation queues the SIGCHLD I 

44940 signal, then if ivait() or zvaitpid () returns because the status of a child process is available, any I 

44941 pending SIGCHLD signal associated with the process ID of the child process shall be discarded. I 

44942 Any other pending SIGCHLD signals shall remain pending. I 

44943 Otherwise, if SIGCHLD is blocked, if zvait() or zvaitpid () return because the status of a child I 

44944 process is available, any pending SIGCHLD signal shall be cleared unless the status of another I 

44945 child process is available. I 

44946 For all other conditions, it is unspecified whether child status will be available when a SIGCHLD I 

44947 signal is delivered. I 

44948 There may be additional implementation-dependent circumstances under which zvait () or I 

44949 zvaitpid () report status. This shall not occur unless the calling process or one of its child processes I 

44950 explicitly makes use of a non-standard extension. In these cases the interpretation of the I 

44951 reported status is implementation-dependent. I 

44952 xsi If a parent process terminates without waiting for all of its child processes to terminate, the 

44953 remaining child processes shall be assigned a new parent process ID corresponding to an 

44954 implementation-dependent system process. 

44955 RETURN VALUE 

44956 If zvait () or zvaitpid () returns because the status of a child process is available, these functions 

44957 shall return a value equal to the process ID of the child process for which status is reported. If I 

44958 zvait () or zvaitpid () returns due to the delivery of a signal to the calling process, -1 shall be 

44959 returned and errno set to [EINTR]. If zvaitpid () was invoked with WNOHANG set in options, it 

44960 has at least one child process specified by pid for which status is not available, and status is not I 

44961 available for any process specified by pid, 0 is returned. Otherwise, (pid_t)-l shall be returned, I 

44962 and errno set to indicate the error. 

44963 ERRORS 

44964 The zvait ( ) function shall fail if: 

44965 [ECHILD] The calling process has no existing unwaited-for child processes. 

44966 [EINTR] The function was interrupted by a signal. The value of the location pointed to 

44967 by stat_loc is undefined. 

44968 The zvaitpid () function shall fail if: 

44969 [ECHILD] The process specified by pid does not exist or is not a child of the calling I 

44970 process, or the process group specified by pid does not exist or does not have I 

44971 any member process that is a child of the calling process. I 

44972 [EINTR] The function was interrupted by a signal. The value of the location pointed to 

44973 by stat_loc is undefined. 

44974 [EINVAL] The options argument is not valid. 
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44975 EXAMPLES 

44976 None. 

44977 APPLICATION USAGE 

44978 None. 

44979 RATIONALE 

44980 A call to the wait () or zvaitpid () function only returns status on an immediate child process of the I 

44981 calling process; that is, a child that was produced by a single fork( ) call (perhaps followed by an I 

44982 exec or other function calls) from the parent. If a child produces grandchildren by further use of 

44983 /ork(), none of those grandchildren nor any of their descendants affect the behavior of a zvait ( ) 

44984 from the original parent process. Nothing in this volume of IEEE Std. 1003.1-200x prevents an 

44985 implementation from providing extensions that permit a process to get status from a grandchild I 

44986 or any other process, but a process that does not use such extensions must be guaranteed to see I 

44987 status from only its direct children. I 

44988 The zvaitpid () function is provided for three reasons: 

44989 1. To support job control 

44990 2. To permit a non-blocking version of the zvait () function 

44991 3. To permit a library routine, such as system() or pclose(), to wait for its children without 

44992 interfering with other terminated children for which the process has not waited 

44993 The first two of these facilities are based on the zvait3() function provided by 4.3 BSD. The 

44994 function uses the options argument, which is identical to an argument to zvait3(). The 

44995 WUNTRACED flag is used only in conjunction with job control on systems supporting job 

44996 control. Its name comes from 4.3 BSD and refers to the fact that there are two types of stopped 

44997 processes in that implementation: processes being traced via the ptrace( ) debugging facility and 

44998 (untraced) processes stopped by job control signals. Since ptrace( ) is not part of this volume of 

44999 IEEE Std. 1003.1-200x, only the second type is relevant. The name WUNTRACED was retained 

45000 because its usage is the same, even though the name is not intuitively meaningful in this context. 

45001 The third reason for the zvaitpid () function is to permit independent sections of a process to 

45002 spawn and wait for children without interfering with each other. For example, the following 

45003 problem occurs in developing a portable shell, or command interpreter: 

45004 stream = popen (" /bin/true ") ; 

45005 (void) system (" sleep 100"); 

45006 (void) pclose (stream) ; 

45007 On all historical implementations, the final pclose () fails to reap the zvait () status of the popen (). I 

45008 The status values are retrieved by macros, rather than given as specific bit encodings as they are 

45009 in most historical implementations (and thus expected by existing programs). This was 

45010 necessary to eliminate a limitation on the number of signals an implementation can support that 

45011 was inherent in the traditional encodings. This volume of IEEE Std. 1003.1-200x does require that I 

45012 a status value of zero corresponds to a process calling _exit( 0), as this is the most common I 

45013 encoding expected by existing programs. Some of the macro names were adopted from 4.3 BSD. 

45014 These macros syntactically operate on an arbitrary integer value. The behavior is undefined 

45015 unless that value is one stored by a successful call to zvait () or zvaitpid () in the location pointed 

45016 to by the stat_loc argument. An early proposal attempted to make this clearer by specifying each 

45017 argument as *stat_loc rather than stat_val . However, that did not follow the conventions of other 

45018 specifications in this volume of IEEE Std. 1003.1-200x or traditional usage. It also could have 

45019 implied that the argument to the macro must literally be *stat_loc; in fact, that value can be 

45020 stored or passed as an argument to other functions before being interpreted by these macros. 
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The extension that affects wait() and waitpid () and is common in historical implementations is 
the ptrace() function. It is called by a child process and causes that child to stop and return a I 
status that appears identical to the status indicated by WIFSTOPPED. The status of ptrace() I 
children is traditionally returned regardless of the WUNTRACED flag (or by the wait{) 
function). Most applications do not need to concern themselves with such extensions because 
they have control over what extensions they or their children use. However, applications, such 
as command interpreters, that invoke arbitrary processes may see this behavior when those 
arbitrary processes misuse such extensions. 

Implementations that support core file creation or other implementation-dependent actions on 
termination of some processes traditionally provide a bit in the status returned by wait() to I 
indicate that such actions have occurred. I 

Allowing the ivait () family of functions to discard a pending SIGCHLD signal that is associated I 
with a successfully waited-for child process puts them into the sigwait( ) and s igzvaitinfo() I 
category with respect to SIGCHLD. I 

This definition allows implementations to treat a pending SIGCHLD signal as accepted by the I 
process in ivait (), with the same meaning of "accepted" as when that word is applied to the I 
sigzvait () family of functions. I 

Allowing the wait () family of functions to behave this way permits an implementation to be able I 
to deal precisely with SIGCHLD signals. I 

In particular, an implementation that does accept (discard) the SIGCHLD signal can make the I 
following guarantees regardless of the queuing depth of signals in general (the list of waitable I 
children can hold the SIGCHLD queue): I 

1. If a SIGCHLD signal handler is established via sigadion() without the SA_RESETHAND I 

flag, SIGCHLD signals can be accurately counted; that is, exactly one SIGCHLD signal will I 
be delivered to or accepted by the process for every child process that terminates. I 

2. A single wait () issued from a SIGCHLD signal handler can be guaranteed to return I 

immediately with status information for a child process. I 

3. When SA_SIGINLO is requested, the SIGCHLD signal handler can be guaranteed to I 

receive a non-NULL pointer to a siginfo_t structure that describes a child process for I 
which a wait via waitpid () or zvaitid () will not block or fail. I 

4. The system () function will not cause a processs SIGCHLD handler to be called as a result of I 

the fork () /exec executed within system () because system () will accept the SIGCHLD signal I 
when it performs a waitpid () for its child process. This is a desirable behavior of system () I 
so that it can be used in a library without causing side effects to the application linked with I 
the library. I 

An implementation that does not permit the ivait () family of functions to accept (discard) a I 
pending SIGCHLD signal associated with a successfully waited-for child, cannot make the I 
guarantees described above for the following reasons: I 

Guarantee #1 I 

Although it might be assumed that reliable queuing of all SIGCHLD signals generated by I 
the system can make this guarantee, the counter example is the case of a process that blocks I 
SIGCHLD and performs an indefinite loop of fork () /wait () operations. If the I 
implementation supports queued signals, then eventually the system will run out of I 
memory for the queue. The guarantee cannot be made because there must be some limit to I 
the depth of queuing. I 
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45066 Guarantees #2 and #3 I 

45067 These cannot be guaranteed unless the wait () family of functions accepts the SIGCHLD I 

45068 signal. Otherwise, a fork()/zvait() executed while SIGCHLD is blocked (as in the system () I 

45069 function) will result in an invocation of the handler when SIGCHLD is unblocked, after the I 

45070 process has disappeared. I 

45071 Guarantee #4 I 

45072 Although possible to make this guarantee, system () would have to set the SIGCHLD I 

45073 handler to SIG_DFL so that the SIGCHLD signal generated by its fork ( ) would be discarded I 

45074 (the SIGCHLD default action is to be ignored), then restore it to its previous setting. This I 

45075 would have the undesirable side effect of discarding all SIGCHLD signals pending to the I 

45076 process. I 

45077 FUTURE DIRECTIONS I 

45078 None. 

45079 SEE ALSO 

45080 exec, exit (), fork (), ivaitid ( ), the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

45081 <sys/types.h>, <sys/wait.h> 

45082 CHANGE HISTORY 

45083 First released in Issue 1. 

45084 Derived from Issue 1 of the SVID. 

45085 Issue 4 

45086 The <sys/types.h> header is now marked as optional (OH); this header need not be included on 

45087 XSI-conformant systems. 

45088 Error return values throughout the DESCRIPTION and RETURN VALUE sections are changed 

45089 to show the proper casting (that is, (pid_t)-l). 

45090 The words "If the implementation supports job control" are removed from the description of 

45091 WUNTRACED. This is because job control is defined as mandatory for Issue 4 conforming 

45092 implementations. 

45093 The following change is incorporated for alignment with the ISO POSIX-1 standard: 

45094 • Text describing conditions under which 0 is returned when WNOHANG is set in options is 

45095 added to the RETURN VALUE section. 

45096 Issue 4, Version 2 

45097 The zvaitpid () function is added. 

45098 The following changes are incorporated in the DESCRIPTION for X/OPEN UNIX conformance: 

45099 • The WCONTINUED options flag and the WIFCONTINUED(staf_ZYz/) macro are added. 

45100 • Text following the list of options flags explains the implications of setting the 

45101 SA_NOCLDWAIT signal flag, or setting SIGCHLD to SIG_IGN. 

45102 • Text following the list of macros, which explains what macros return non-zero values in 

45103 certain cases, is expanded and the value of the WCONTINUED flag on the previous call to 

45104 zvaitpid () is taken into account. 

45105 Issue 5 

45106 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 
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Issue 6 

In the SYNOPSIS, the inclusion of <sys/types.h> is no longer required. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The requirement to include <sys/types.h> has been removed. Although <sys/types.h> was 
required for conforming implementations of previous POSIX specifications, it was not 
required for UNIX applications. 

The following changes were made to align with the IEEE P1003.1a draft standard: 

• The processing of the SIGCHLD signal and the [ECHILD] error is clarified. 

The semantics of WIFSTOPPED(stof_i’fl/), WIFEXITED(staf_iYz/), and WIESIGNALED(s tat_va /) 
are defined with respect to posix_spawn () or posix_spaivnp () for alignment with 
IEEE Std. 1003.1d-1999. 
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NAME 

waitid — wait for a child process to change state 

SYNOPSIS 

xsi tinclude <sys/wait.h> 

int waitid(idtype_t idtype, id_t id, siginfo_t * infop, int options); 


DESCRIPTION 

The waitid () function shall suspend the calling thread until one child of the process containing 
the calling thread changes state. It records the current state of a child in the structure pointed to 
by infop. If a child process changed state prior to the call to waitid (), zvaitid () returns 
immediately. If more than one thread is suspended in zvait( ) or waitpid () waiting termination of 
the same process, exactly one thread returns the process status at the time of the target process 
termination 

The idtype and id arguments are used to specify which children waitid () waits for. 

If idtype is P_PID, zvaitid () shall wait for the child with a process ID equal to (pid_t)zd. 

If idtype is P_PGID, zvaitid () shall wait for any child with a process group ID equal to (pid_t)zd. 

If idtype is P_ALL, zvaitid () shall wait for any children and id is ignored. 

The options argument is used to specify which state changes zvaitid () shall wait for. It is formed 
by OR'ing together one or more of the following flags: 

WEXITED Wait for processes that have exited. 

WSTOPPED Status shall be returned for any child that has stopped upon receipt of a signal. 

WCONTINUED Status shall be returned for any child that was stopped and has been 
continued. 

WNOHANG Return immediately if there are no children to wait for. 

WNOWAIT Keep the process whose status is returned in infop in a waitable state. This 
shall not affect the state of the process; the process may be waited for again 
after this call completes. 

The application shall ensure that the infop argument points to a siginfo_t structure. If zvaitid () 
returns because a child process was found that satisfied the conditions indicated by the 
arguments idtype and options, then the structure pointed to by infop shall be filled in by the 
system with the status of the process. The si_signo member shall always be equal to SIGCHLD. 

RETURN VALUE 

Notes to Reviewers 

This section zvith side shading zvill not appear in the final copy. - Ed. 

Dl, XSH, ERN 416 points out an omission. The following text is proposed: "If WNOHANG was 
specified and there are no children to wait for, 0 shall be returned." 

If zvaitid () returns due to the change of state of one of its children, 0 shall be returned. Otherwise, 
-1 shall be returned and errno set to indicate the error. 

ERRORS 

The zvaitid () function shall fail if: 

[ECHILD] The calling process has no existing unwaited-for child processes. 
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45160 [EINTR] The ivaitid () function was interrupted by a signal. 

45161 [EINVAL] An invalid value was specified for options, or idtxjpe and id specify an invalid 

45162 set of processes. 

45163 EXAMPLES 

45164 None. 

45165 APPLICATION USAGE 

45166 None. 

45167 RATIONALE 

45168 None. 

45169 FUTURE DIRECTIONS 

45170 None. 

45171 SEE ALSO 

45172 exec, exit(), wait{ ), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

45173 <sys/wait.h> 

45174 CHANGE HISTORY 

45175 First released in Issue 4, Version 2. 

45176 Issue 5 

45177 Moved from X/OPEN UNIX extension to BASE. 

45178 The DESCRIPTION is updated for alignment with the POSIX Threads Extension. 

45179 Issue 6 

45180 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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45181 NAME 

45182 waitpid — wait for a child process to stop or terminate 

45183 SYNOPSIS 

45184 #include <sys/wait.h> 

45185 pid_t waitpid (pid_t pid, int *stat_loc, int options) ; 

45186 DESCRIPTION 

45187 Refer to wait (). 
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45188 NAME 

45189 wcrtomb — convert a wide-character code to a character (restartable) 

45190 SYNOPSIS 

45191 tinclude <stdio.h> 

45192 size_t wcrtomb (char *s, wchar_t wc, mbstate_t *ps) ; 

45193 DESCRIPTION 

45194 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45195 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45196 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45197 If s is a null pointer, the zvcrtomb( ) function shall be equivalent to the call: 

45198 wcrtomb (buf, L'\0', ps) 

45199 where buf is an internal buffer. 

45200 If s is not a null pointer, the wcrtomb ( ) function shall determine the number of bytes needed to 

45201 represent the character that corresponds to the wide character given by zvc (including any shift 

45202 sequences), and stores the resulting bytes in the array whose first element is pointed to by s. At 

45203 most {MB_CUR_MAX} bytes are stored. If wc is a null wide character, a null byte is stored, 

45204 preceded by any shift sequence needed to restore the initial shift state. The resulting state 

45205 described is the initial conversion state. 

45206 If ps is a null pointer, the wcrtomb() function uses its own internal mbstate_t object, which is I 

45207 initialized at program start-up to the initial conversion state. Otherwise, the mbstate_t object I 

45208 pointed to by ps is used to completely describe the current conversion state of the associated 

45209 character sequence. The implementation shall behave as if no function defined in this volume of 

45210 IEEE Std. 1003.1-200x calls wcrtomb (). 

45211 cx If the application uses any of the _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS I 

45212 interfaces, the application shall ensure that the ivcrtomb( ) function is called with a non-NULL ps I 

45213 argument. 

45214 xsi The behavior of this function shall be affected by the LC_CTYPE category of the current locale. 

45215 RETURN VALUE 

45216 The wcrtomb () function shall return the number of bytes stored in the array object (including any 

45217 shift sequences). When zvc is not a valid wide character, an encoding error shall occur. In this 

45218 case, the function shall store the value of the macros [EILSEQ] in errno and shall return 

45219 (size. _td)-l ; the conversion state shall be undefined. 

45220 ERRORS 

45221 The zvcrtomb( ) function may fail if: 

45222 cx [EINVAL] ps points to an object that contains an invalid conversion state. 

45223 [EILSEQ] Invalid wide-character code is detected. 
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45224 EXAMPLES 

45225 None. 

45226 APPLICATION USAGE 

45227 None. 

45228 RATIONALE 

45229 None. 

45230 FUTURE DIRECTIONS 

45231 None. 

45232 SEE ALSO 

45233 mbsinit( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

45234 CHANGE HISTORY 

45235 First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 

45236 (E). I 

45237 Issue 6 

45238 In the DESCRIPTION, a note on using this function in a threaded application is added. 

45239 Extensions beyond the ISO C standard are now marked. I 

45240 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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45241 NAME 

45242 wcscat — concatenate two wide-character strings 

45243 SYNOPSIS 

45244 #include <wchar.h> 

45245 wchar_t *wcscat (wchar_t *wsl, const wchar_t *ws2) ; 

45246 DESCRIPTION 

45247 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45248 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45249 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45250 The wcscat {) function shall append a copy of the wide-character string pointed to by zvs2 

45251 (including the terminating null wide-character code) to the end of the wide-character string 

45252 pointed to by wsl. The initial wide-character code of ws2 overwrites the null wide-character 

45253 code at the end of wsl. If copying takes place between objects that overlap, the behavior is 

45254 undefined. 

45255 RETURN VALUE 

45256 The wcscat () function shall return wsl ; no return value is reserved to indicate an error. 

45257 ERRORS 

45258 No errors are defined. 

45259 EXAMPLES 

45260 None. 

45261 APPLICATION USAGE 

45262 None. 

45263 RATIONALE 

45264 None. 

45265 FUTURE DIRECTIONS 

45266 None. 

45267 SEE ALSO 

45268 wcsncat( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

45269 CHANGE HISTORY 

45270 First released in Issue 4. 

45271 Derived from the MSE working draft. 

45272 Issue 6 

45273 The Open Group corrigenda item U040/2 has been applied. In the RETURN VALUE section, si 

45274 is changed to wsl. 
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NAME 

wcschr — wide-character string scanning operation 

SYNOPSIS 

#include <wchar.h> 

wchar_t *wcschr(const wchar_t *ws, wchar_t wc ); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The wcschr () function shall locate the first occurrence of wc in the wide-character string pointed 
to by zvs . The application shall ensure that the value of zvc is a character representable as a type I 
wchar_t and a wide-character code corresponding to a valid character in the current locale. The I 
terminating null wide-character code is considered to be part of the wide-character string. I 

RETURN VALUE 

Upon completion, zvcschr () shall return a pointer to the wide-character code, or a null pointer if 
the wide-character code is not found. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

zvcsrchr (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

CHANGE HISTORY 

First released in Issue 4. 

Derived from the MSE working draft. I 

Issue 6 I 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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45308 NAME 

45309 wcscmp — compare two wide-character strings 

45310 SYNOPSIS 

45311 #include <wchar.h> 

45312 int wcscmp (const wchar_t *wsl, const wchar_t *ws2 ); 

45313 DESCRIPTION 

45314 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45315 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45316 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45317 The wcscmp () function shall compare the wide-character string pointed to by wsl to the wide- 

45318 character string pointed to by wsl. 

45319 The sign of a non-zero return value is determined by the sign of the difference between the 

45320 values of the first pair of wide-character codes that differ in the objects being compared. 

45321 RETURN VALUE 

45322 Upon completion, wcscmp () shall return an integer greater than, equal to, or less than 0, if the 

45323 wide-character string pointed to by wsl is greater than, equal to, or less than the wide-character 

45324 string pointed to by wsl , respectively. 

45325 ERRORS 

45326 No errors are defined. 

45327 EXAMPLES 

45328 None. 

45329 APPLICATION USAGE 

45330 None. 

45331 RATIONALE 

45332 None. 

45333 FUTURE DIRECTIONS 

45334 None. 

45335 SEE ALSO 

45336 wcsncmp( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

45337 CHANGE HISTORY 

45338 First released in Issue 4. 

45339 Derived from the MSE working draft. 
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NAME 

wcscoll — wide-character string comparison using collating information 

SYNOPSIS 

#include <wchar.h> 

int wcscoll(const wchar_t *wsl, const wchar_t *ws2) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The wcscoll () function shall compare the wide-character string pointed to by wsl to the wide- 
character string pointed to by zvs2, both interpreted as appropriate to the LC_COLLATE category 
of the current locale. 

cx The zvcscoll () function shall not change the setting of errno if successful. 

An application wishing to check for error situations should set errno to 0 before calling zvcscoll (). 

If errno is non-zero on return, an error has occurred. 

RETURN VALUE 

Upon successful completion, zvcscoll () shall return an integer greater than, equal to, or less than 
0, according to whether the wide-character string pointed to by zvsl is greater than, equal to, or 
less than the wide-character string pointed to by zvs2, when both are interpreted as appropriate 
cx to the current locale. On error, zvcscoll () may set errno, but no return value is reserved to indicate 

an error. 

ERRORS 

The zvcscoll () function may fail if: 

[EINVAL] The zvsl or zvs2 arguments contain wide-character codes outside the domain of 

the collating sequence. 

EXAMPLES 

None. 

APPLICATION USAGE 

The wcsxfrm( ) and wcscmp () functions should be used for sorting large lists. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

wcscmp (), zvcsxfrm(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

<wchar.h> 

CHANGE HISTORY 

First released in Issue 4. 

Derived from the MSE working draft. 

Issue 5 

Moved from ENHANCED I18N to BASE and the [ENOSYS] error is removed. 

The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 
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45382 NAME 

45383 wcscpy — copy a wide-character string 

45384 SYNOPSIS 

45385 tinclude <wchar.h> 

45386 wchar_t *wcscpy (wchar_t *wsl, const wchar_t *ws2) ; 

45387 DESCRIPTION 

45388 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45389 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45390 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45391 The zvcscpy () function shall copy the wide-character string pointed to by ws2 (including the 

45392 terminating null wide-character code) into the array pointed to by wsl . If copying takes place 

45393 between objects that overlap, the behavior is undefined. 

45394 RETURN VALUE 

45395 The zvcscpy () function shall return zvsl ; no return value is reserved to indicate an error. 

45396 ERRORS 

45397 No errors are defined. 

45398 EXAMPLES 

45399 None. 

45400 APPLICATION USAGE 

45401 Wide-character code movement is performed differently in different implementations. Thus 

45402 overlapping moves may yield surprises. 

45403 RATIONALE 

45404 None. 

45405 FUTURE DIRECTIONS 

45406 None. 

45407 SEE ALSO 

45408 zvcsncpy( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

45409 CHANGE HISTORY 

45410 First released in Issue 4. 

45411 Derived from the MSE working draft. 
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45412 NAME 

45413 wcscspn — get length of a complementary wide substring 

45414 SYNOPSIS 

45415 tinclude <wchar.h> 

45416 size_t wcscspn (const wchar_t *wsl, const wchar_t *ws2) ; 

45417 DESCRIPTION 

45418 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45419 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45420 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45421 The wcscspn () function shall compute the length of the maximum initial segment of the wide- 

45422 character string pointed to by wsl which consists entirely of wide-character codes not from the 

45423 wide-character string pointed to by zvs2. 

45424 RETURN VALUE 

45425 The wcscspn () function shall return the length of the initial substring of wsl ; no return value is 

45426 reserved to indicate an error. 

45427 ERRORS 

45428 No errors are defined. 

45429 EXAMPLES 

45430 None. 

45431 APPLICATION USAGE 

45432 None. 

45433 RATIONALE 

45434 None. 

45435 FUTURE DIRECTIONS 

45436 None. 

45437 SEE ALSO 

45438 ivcsspn{), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

45439 CHANGE HISTORY 

45440 First released in Issue 4. 

45441 Derived from the MSE working draft. 

45442 Issue 5 

45443 The RETURN VALUE section is updated to indicate that wcscspn () returns the length of wsl, 

45444 rather than wsl itself. 
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NAME 

wcsftime — convert date and time to a wide-character string 

SYNOPSIS 

#include <wchar.h> 

size_t wcsftime(wchar_t *wcs, size_t maxsize, const wchar_t * format, 
const struct tm *timptr); 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The wcsftime( ) function shall be equivalent to the strftime( ) function, except that: 

• The argument zvcs points to the initial element of an array of wide characters into which the 
generated output is to be placed. 

• The argument maxsize indicates the maximum number of wide characters to be placed in the 
output array. 

• The argument format is a wide-character string and the conversion specifications are replaced 
by corresponding sequences of wide characters. 

• The return value indicates the number of wide characters placed in the output array. 

If copying takes place between objects that overlap, the behavior is undefined. 

RETURN VALUE 

If the total number of resulting wide-character codes including the terminating null wide- 
character code is no more than maxsize, wcsftime () shall return the number of wide-character 
codes placed into the array pointed to by zvcs, not including the terminating null wide-character 
code. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

strftimei ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

CHANGE HISTORY 

First released in Issue 4. 


Issue 5 

Moved from ENHANCED I18N to BASE and the [ENOSYS] error is removed. 

Aligned with ISO/IEC 9899:1990/Amendment 1:1995 (E). Specifically, the type of the format 
rgument is changed from const char* to const wchar t*. 
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45487 NAME 

45488 wcslen — get wide-character string length 

45489 SYNOPSIS 

45490 tinclude <wchar.h> 

45491 size_t wcslen (const wchar_t *ws) ; 

45492 DESCRIPTION 

45493 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45494 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45495 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45496 The zvcslen () function shall compute the number of wide-character codes in the wide-character 

45497 string to which zvs points, not including the terminating null wide-character code. 

45498 RETURN VALUE 

45499 The zvcslen () function shall return the length of zvs ; no return value is reserved to indicate an 

45500 error. 

45501 ERRORS 

45502 No errors are defined. 

45503 EXAMPLES 

45504 None. 

45505 APPLICATION USAGE 

45506 None. 

45507 RATIONALE 

45508 None. 

45509 FUTURE DIRECTIONS 

45510 None. 

45511 SEE ALSO 

45512 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

45513 CHANGE HISTORY 

45514 First released in Issue 4. 

45515 Derived from the MSE working draft. 
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45516 NAME 

45517 wcsncat — concatenate a wide-character string with part of another 

45518 SYNOPSIS 

45519 #include <wchar.h> 

45520 wchar_t *wcsncat (wchar_t *wsl, const wchar_t *ws2, size_t n) ; 

45521 DESCRIPTION 

45522 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45523 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45524 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45525 The wcsncat() function shall append not more than n wide-character codes (a null wide- 

45526 character code and wide-character codes that follow it are not appended) from the array pointed 

45527 to by zvs 2 to the end of the wide-character string pointed to by wsl . The initial wide-character 

45528 code of wsl overwrites the null wide-character code at the end of wsl. A terminating null wide- 

45529 character code is always appended to the result. If copying takes place between objects that 

45530 overlap, the behavior is undefined. 

45531 RETURN VALUE 

45532 The wcsncat () function shall return wsl ; no return value is reserved to indicate an error. 

45533 ERRORS 

45534 No errors are defined. 

45535 EXAMPLES 

45536 None. 

45537 APPLICATION USAGE 

45538 None. 

45539 RATIONALE 

45540 None. 

45541 FUTURE DIRECTIONS 

45542 None. 

45543 SEE ALSO 

45544 wcscat{ ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

45545 CHANGE HISTORY 

45546 First released in Issue 4. 

45547 Derived from the MSE working draft. 
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45548 NAME 

45549 wcsncmp — compare part of two wide-character strings 

45550 SYNOPSIS 

45551 #include <wchar.h> 

45552 int wcsncmp (const wchar_t *wsl, const wchar_t *ws2, size_t n) ; 

45553 DESCRIPTION 

45554 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45555 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45556 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45557 The wcsncmpO function shall compare not more than n wide-character codes (wide-character 

45558 codes that follow a null wide-character code are not compared) from the array pointed to by wsl 

45559 to the array pointed to by wsl. 

45560 The sign of a non-zero return value is determined by the sign of the difference between the 

45561 values of the first pair of wide-character codes that differ in the objects being compared. 

45562 RETURN VALUE 

45563 Upon successful completion, wcsncmpO shall return an integer greater than, equal to, or less 

45564 than 0, if the possibly null-terminated array pointed to by wsl is greater than, equal to, or less 

45565 than the possibly null-terminated array pointed to by wsl , respectively. 

45566 ERRORS 

45567 No errors are defined. 

45568 EXAMPLES 

45569 None. 

45570 APPLICATION USAGE 

45571 None. 

45572 RATIONALE 

45573 None. 

45574 FUTURE DIRECTIONS 

45575 None. 

45576 SEE ALSO 

45577 wcscmp( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

45578 CHANGE HISTORY 

45579 First released in Issue 4. 

45580 Derived from the MSE working draft. 
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45581 NAME 

45582 wcsncpy — copy part of a wide-character string 

45583 SYNOPSIS 

45584 #include <wchar.h> 

45585 wchar_t *wcsncpy(wchar_t *wsl, const wchar_t *ws2, size_t n) ; 

45586 DESCRIPTION 

45587 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45588 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45589 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45590 The wcsncpyO function shall copy not more than n wide-character codes (wide-character codes 

45591 that follow a null wide-character code are not copied) from the array pointed to by ws2 to the 

45592 array pointed to by wsl. If copying takes place between objects that overlap, the behavior is 

45593 undefined. 

45594 If the array pointed to by zvs2 is a wide-character string that is shorter than n wide-character 

45595 codes, null wide-character codes are appended to the copy in the array pointed to by wsl , until n 

45596 wide-character codes in all are written. 

45597 RETURN VALUE 

45598 The wcsncpy () function shall return wsl ; no return value is reserved to indicate an error. 

45599 ERRORS 

45600 No errors are defined. 

45601 EXAMPLES 

45602 None. 

45603 APPLICATION USAGE 

45604 Wide-character code movement is performed differently in different implementations. Thus, 

45605 overlapping moves may yield surprises. 

45606 If there is no null wide-character code in the first n wide-character codes of the array pointed to 

45607 by ws2 , the result is not null-terminated. 

45608 RATIONALE 

45609 None. 

45610 FUTURE DIRECTIONS 

45611 None. 

45612 SEE ALSO 

45613 zvcscpy( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

45614 CHANGE HISTORY 

45615 First released in Issue 4. 

45616 Derived from the MSE working draft. 
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45617 NAME 

45618 wcspbrk — scan wide-character string for a wide-character code 

45619 SYNOPSIS 

45620 tinclude <wchar.h> 

45621 wchar_t *wcspbrk(const wchar_t *wsl, const wchar_t *ws2 ); 

45622 DESCRIPTION 

45623 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45624 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45625 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45626 The zvcspbrk( ) function shall locate the first occurrence in the wide-character string pointed to by 

45627 zvsl of any wide-character code from the wide-character string pointed to by zvs2. 

45628 RETURN VALUE 

45629 Upon successful completion, zvcspbrk( ) shall return a pointer to the wide-character code or a null 

45630 pointer if no wide-character code from zvs2 occurs in zvsl. 

45631 ERRORS 

45632 No errors are defined. 

45633 EXAMPLES 

45634 None. 

45635 APPLICATION USAGE 

45636 None. 

45637 RATIONALE 

45638 None. 

45639 FUTURE DIRECTIONS 

45640 None. 

45641 SEE ALSO 

45642 zvcschri ), zvcsrchr( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

45643 CHANGE HISTORY 

45644 First released in Issue 4. 

45645 Derived from the MSE working draft. 
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NAME 

wcsrchr — wide-character string scanning operation 

SYNOPSIS 

#include <wchar.h> 

wchar_t *wcsrchr(const wchar_t *ws, wchar_t wc) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The wcsrchr () function shall locate the last occurrence of zvc in the wide-character string pointed 
to by zvs . The application shall ensure that the value of zvc is a character representable as a type I 
wchar_t and a wide-character code corresponding to a valid character in the current locale. The I 
terminating null wide-character code is considered to be part of the wide-character string. I 

RETURN VALUE 

Upon successful completion, zvcsrchr () shall return a pointer to the wide-character code or a null 
pointer if zvc does not occur in the wide-character string. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

zvcschr(), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

CHANGE HISTORY 

First released in Issue 4. 

Derived from the MSE working draft. I 

Issue 6 I 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 


System Interfaces, Issue 6 


1503 



wcsrtombsO 


System Interfaces 


45679 
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NAME 

wcsrtombs — convert a wide-character string to a character string (restartable) 

SYNOPSIS 

#include <wchar.h> 

size_t wcsrtombs(char *dst, const wchar_t **src, size_t len, 
mbstate_t *ps) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The wcsrtombs() function shall convert a sequence of wide characters from the array indirectly 
pointed to by src into a sequence of corresponding characters, beginning in the conversion state 
described by the object pointed to by ps . If dst is not a null pointer, the converted characters are 
then stored into the array pointed to by dst. Conversion continues up to and including a 
terminating null wide character, which is also stored. Conversion stops earlier in the following 
cases: 

• When a code is reached that does not correspond to a valid character 

• When the next character would exceed the limit of len total bytes to be stored in the array 
pointed to by dst (and dst is not a null pointer) 

Each conversion takes place as if by a call to the wcrtomb( ) function. 

If dst is not a null pointer, the pointer object pointed to by src is assigned either a null pointer (if 
conversion stopped due to reaching a terminating null wide character) or the address just past 
the last wide character converted (if any). If conversion stopped due to reaching a terminating 
null wide character, the resulting state described is the initial conversion state. 

If ps is a null pointer, the wcsrtombsO function uses its own internal mbstate_t object, which is I 
initialized at program start-up to the initial conversion state. Otherwise, the mbstate_t object I 
pointed to by ps is used to completely describe the current conversion state of the associated 
character sequence. The implementation shall behave as if no function defined in this volume of 
IEEE Std. 1003.1-200x calls zvcsrtombs (). 

cx If the application uses any of the _POSIX_THREAD_SAFE_FUNCTIONS or _POSIX_THREADS I 
interfaces, the application shall ensure that the zucsrtombs( ) function is called with a non-NULL I 
ps argument. 

xsi The behavior of this function shall be affected by the LC_CTYPE category of the current locale. 

RETURN VALUE 

If conversion stops because a code is reached that does not correspond to a valid character, an 
encoding error occurs. In this case, the ivcsrtombsO function shall store the value of the macro 
[EILSEQ] in errno and return (size_t)-l; the conversion state is undefined. Otherwise, it shall 
return the number of bytes in the resulting character sequence, not including the terminating 
null (if any). 

ERRORS 

The ivcsrtombs( ) function may fail if: 

cx [EINVAL] ps points to an object that contains an invalid conversion state. 

[EILSEQ] A wide-character code does not correspond to a valid character. 
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EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

mbsinit(), wcrtomb(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 

<wchar.h> 

CHANGE HISTORY 

First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 
(E). I 

Issue 6 

In the DESCRIPTION, a note on using this function in a threaded application is added. 

Extensions beyond the ISO C standard are now marked. I 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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45740 NAME 

45741 wcsspn — get length of a wide substring 

45742 SYNOPSIS 

45743 tinclude <wchar.h> 

45744 size_t wcsspn (const wchar_t *wsl, const wchar_t *ws2) ; 

45745 DESCRIPTION 

45746 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45747 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45748 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45749 The wcsspn() function shall compute the length of the maximum initial segment of the wide- 

45750 character string pointed to by wsl which consists entirely of wide-character codes from the 

45751 wide-character string pointed to by ws2. 

45752 RETURN VALUE 

45753 The zvcsspn () function shall return the length of the initial substring of wsl ; no return value is 

45754 reserved to indicate an error. 

45755 ERRORS 

45756 No errors are defined. 

45757 EXAMPLES 

45758 None. 

45759 APPLICATION USAGE 

45760 None. 

45761 RATIONALE 

45762 None. 

45763 FUTURE DIRECTIONS 

45764 None. 

45765 SEE ALSO 

45766 ivcscspn (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

45767 CHANGE HISTORY 

45768 First released in Issue 4. 

45769 Derived from the MSE working draft. 

45770 Issue 5 

45771 The RETURN VALUE section is updated to indicate that zvcsspn () returns the length of zvsl 

45772 rather that zvsl itself. 
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45773 NAME 

45774 wcsstr — find a wide-character substring 

45775 SYNOPSIS 

45776 #include <wchar.h> 

45777 wchar_t *wcsstr (const wchar_t *wsl, const wchar_t *ws2) ; 

45778 DESCRIPTION 

45779 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45780 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45781 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45782 The wcsstr{) function shall locate the first occurrence in the wide-character string pointed to by 

45783 wsl of the sequence of wide characters (excluding the terminating null wide character) in the 

45784 wide-character string pointed to by ws2. 

45785 RETURN VALUE 

45786 Upon successful completion, zvcsstr( ) shall return a pointer to the located wide-character string, I 

45787 or a null pointer if the wide-character string is not found. 

45788 If zvs2 points to a wide-character string with zero length, the function shall return zvsl. 

45789 ERRORS 

45790 No errors are defined. 

45791 EXAMPLES 

45792 None. 

45793 APPLICATION USAGE 

45794 None. 

45795 RATIONALE 

45796 None. 

45797 FUTURE DIRECTIONS 

45798 None. 

45799 SEE ALSO 

45800 zvcschr( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

45801 CHANGE HISTORY 

45802 First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 

45803 (E). I 
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45804 NAME 

45805 wcstod — convert a wide-character string to a double-precision number 

45806 SYNOPSIS 

45807 #include <wchar.h> 

45808 double wcstod (const wchar_t *nptr, wchar_t **endptr)} 

45809 DESCRIPTION 

45810 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45811 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45812 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45813 The zvcstod() function shall convert the initial portion of the wide-character string pointed to by 

45814 nptr to double representation. First it decomposes the input wide-character string into three 

45815 parts: 

45816 1. An initial, possibly empty, sequence of white-space wide-character codes (as specified by 

45817 iswspace ()) 

45818 2. A subject sequence interpreted as a floating-point constant 

45819 3. A final wide-character string of one or more unrecognized wide-character codes, including 

45820 the terminating null wide-character code of the input wide-character string 

45821 Then it attempts to convert the subject sequence to a floating-point number, and returns the 

45822 result. 

45823 The expected form of the subject sequence is an optional ' + ' or sign, then a non-empty 

45824 sequence of digits optionally containing a radix character, then an optional exponent part. An 

45825 exponent part consists of ' e' or ' E', followed by an optional sign, followed by one or more 

45826 decimal digits. The subject sequence is defined as the longest initial subsequence of the input 

45827 wide-character string, starting with the first non-white-space wide-character code, that is of the 

45828 expected form. The subject sequence contains no wide-character codes if the input wide- 

45829 character string is empty or consists entirely of white-space wide-character codes, or if the first 

45830 wide-character code that is not white space other than a sign, a digit, or a radix character. 

45831 If the subject sequence has the expected form, the sequence of wide-character codes starting 

45832 with the first digit or the radix character (whichever occurs first) is interpreted as a floating 

45833 constant as defined in the C language, except that the radix character is used in place of a period, 

45834 and that if neither an exponent part nor a radix character appears, a radix character is assumed 

45835 to follow the last digit in the wide-character string. If the subject sequence begins with a minus 

45836 sign, the value resulting from the conversion is negated. A pointer to the final wide-character 

45837 string is stored in the object pointed to by endptr, provided that endptr is not a null pointer. 

45838 cx The radix character is defined in the program's locale (category LC_NUMERIC). In the POSIX 

45839 locale, or in a locale where the radix character is not defined, the radix character shall default to a 

45840 period (' .'). 

45841 cx In other than the C or POSIX locales, other implementation-dependent subject sequences may be 

45842 accepted. 

45843 If the subject sequence is empty or does not have the expected form, no conversion is performed; 

45844 the value of nptr is stored in the object pointed to by endptr, provided that endptr is not a null 

45845 pointer. 

45846 The wcstod () function shall not change the setting of errno if successful. 

45847 Because 0 is returned on error and is also a valid return on success, an application wishing to 

45848 check for error situations should set errno to 0, then call wcstod (), then check errno. 
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RETURN VALUE 

The wcstod() function shall return the converted value, if any. If no conversion could be 
cx performed, 0 shall be returned and errno may be set to [EINVAL]. 

If the correct value is outside the range of representable values, ±HUGE_VAL shall be returned 
(according to the sign of the value), and errno is set to [ERANGE]. 

If the correct value would cause underflow, 0 shall be returned and errno set to [ERANGE]. 

ERRORS 

The zvcstod( ) function shall fail if: 

[ERANGE] The value to be returned would cause overflow or underflow. 

The wcstodO function may fail if: 
cx [EINVAL] No conversion could be performed. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

iswspace (), localeconvO, scanfO, setlocaleO, wcstolO, the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <wchar.h>, the System Interface Definitions volume of I 
IEEE Std. 1003.1-200x, Chapter 7, Locale I 

CHANGE HISTORY 

First released in Issue 4. 

Derived from the MSE working draft. 

Issue 5 

The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 
added if no conversion could be performed. 
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45883 NAME 

45884 wcstok — split wide-character string into tokens 

45885 SYNOPSIS 

45886 #include <wchar.h> 

45887 wchar_t *wcstok (wchar_t *wsl, const wchar_t *ws2, wchar_t **ptr); 

45888 DESCRIPTION 

45889 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45890 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45891 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45892 A sequence of calls to zvcstok () breaks the wide-character string pointed to by wsl into a 

45893 sequence of tokens, each of which is delimited by a wide-character code from the wide-character 

45894 string pointed to by ws2 . The third argument points to a caller-provided wchar_t pointer into 

45895 which the zvcstok() function stores information necessary for it to continue scanning the same 

45896 wide-character string. 

45897 The first call in the sequence has wsl as its first argument, and is followed by calls with a null 

45898 pointer as their first argument. The separator string pointed to by zvs2 may be different from call 

45899 to call. 

45900 The first call in the sequence searches the wide-character string pointed to by zvsl for the first 

45901 wide-character code that is not contained in the current separator string pointed to by zvs2 . If no 

45902 such wide-character code is found, then there are no tokens in the wide-character string pointed 

45903 to by zvsl and zvcstok( ) returns a null pointer. If such a wide-character code is found, it is the start 

45904 of the first token. 

45905 The zvcstok () function then searches from there for a wide-character code that is contained in the 

45906 current separator string. If no such wide-character code is found, the current token extends to 

45907 the end of the wide-character string pointed to by zvsl , and subsequent searches for a token shall 

45908 return a null pointer. If such a wide-character code is found, it is overwritten by a null wide- 

45909 character, which terminates the current token. The zvcstok () function saves a pointer to the 

45910 following wide-character code, from which the next search for a token shall start. 

45911 Each subsequent call, with a null pointer as the value of the first argument, starts searching from 

45912 the saved pointer and behaves as described above. 

45913 The implementation shall behave as if no function calls zvcstok (). 

45914 RETURN VALUE 

45915 Upon successful completion, the zvcstok() function shall return a pointer to the first wide- 

45916 character code of a token. Otherwise, if there is no token, zvcstok () shall return a null pointer. 

45917 ERRORS 

45918 No errors are defined. 

45919 EXAMPLES 

45920 None. 

45921 APPLICATION USAGE 

45922 None. 

45923 RATIONALE 

45924 None. 
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45925 FUTURE DIRECTIONS 

45926 None. 

45927 SEE ALSO 

45928 The System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

45929 CHANGE HISTORY 

45930 First released in Issue 4. 

45931 Issue 5 

45932 Aligned with ISO/IEC 9899:1990/Amendment 1:1995 (E). Specifically, a third argument is 

45933 added to the definition of this function in the SYNOPSIS. 
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45934 NAME 

45935 wcstol — convert a wide-character string to a long integer 

45936 SYNOPSIS 

45937 #include <wchar.h> 

45938 long int wcstol (const wchar_t *nptr, wchar_t **endptr, int base); 

45939 DESCRIPTION 

45940 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

45941 conflict between the requirements described here and the ISO C standard is unintentional. This I 

45942 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

45943 The wcstol () function shall convert the initial portion of the wide-character string pointed to by 

45944 nptr to long int representation. First it decomposes the input wide-character string into three 

45945 parts: 

45946 1. An initial, possibly empty, sequence of white-space wide-character codes (as specified by 

45947 iswspace ()) 

45948 2. A subject sequence interpreted as an integer represented in some radix determined by the 

45949 value of base 

45950 3. A final wide-character string of one or more unrecognized wide-character codes, including 

45951 the terminating null wide-character code of the input wide-character string 

45952 Then it attempts to convert the subject sequence to an integer, and returns the result. 

45953 If base is 0, the expected form of the subject sequence is that of a decimal constant, octal constant, 

45954 or hexadecimal constant, any of which may be preceded by a ' + ' or sign. A decimal 

45955 constant begins with a non-zero digit, and consists of a sequence of decimal digits. An octal 

45956 constant consists of the prefix ' 0' optionally followed by a sequence of the digits 'O' to ' 7' 

45957 only. A hexadecimal constant consists of the prefix "Ox" or "OX" followed by a sequence of the 

45958 decimal digits and letters ' a' (or ' A') to ' f' (or ' F') with values 10 to 15 respectively. 

45959 If the value of base is between 2 and 36, the expected form of the subject sequence is a sequence 

45960 of letters and digits representing an integer with the radix specified by base, optionally preceded 

45961 by a ' + ' or sign, but not including an integer suffix. The letters from ' a' (or ' A') to ' z' 

45962 (or ' Z') inclusive are ascribed the values 10 to 35; only letters whose ascribed values are less 

45963 than that of base are permitted. If the value of base is 16, the wide-character code representations 

45964 of " 0 x" or " 0 X" may optionally precede the sequence of letters and digits, following the sign if 

45965 present. 

45966 The subject sequence is defined as the longest initial subsequence of the input wide-character 

45967 string, starting with the first non-white-space wide-character code that is of the expected form. 

45968 The subject sequence contains no wide-character codes if the input wide-character string is 

45969 empty or consists entirely of white-space wide-character code, or if the first non-white-space 

45970 wide-character code is other than a sign or a permissible letter or digit. 

45971 If the subject sequence has the expected form and base is 0, the sequence of wide-character codes 

45972 starting with the first digit is interpreted as an integer constant. If the subject sequence has the 

45973 expected form and the value of base is between 2 and 36, it is used as the base for conversion, 

45974 ascribing to each letter its value as given above. If the subject sequence begins with a minus sign, 

45975 the value resulting from the conversion is negated. A pointer to the final wide-character string is 

45976 stored in the object pointed to by endptr, provided that endptr is not a null pointer. 

45977 cx In other than the C or POSIX locales, other implementation-dependent subject sequences may be 

45978 accepted. 
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45979 If the subject sequence is empty or does not have the expected form, no conversion is performed; 

45980 the value of nptr is stored in the object pointed to by endptr, provided that endptr is not a null 

45981 pointer. 

45982 The wcstol () function shall not change the setting of errno if successful. 

45983 Because 0, {LONG_MIN}, and |LONG_MAX} are returned on error and are also valid returns on 

45984 success, an application wishing to check for error situations should set errno to 0, then call 

45985 wcstol(), then check errno. 

45986 RETURN VALUE 

45987 Upon successful completion, wcstol () shall return the converted value, if any. If no conversion 

45988 cx could be performed, 0 shall be returned and errno may be set to indicate the error. If the correct 

45989 value is outside the range of representable values, |LONG_MAX[ or {LONG_MIN} shall be 

45990 returned (according to the sign of the value), and errno set to [ERANGE]. 

45991 ERRORS 

45992 The wcstol () function shall fail if: 

45993 cx [EINVAL] The value of base is not supported. 

45994 [ERANGE] The value to be returned is not representable. 

45995 The wcstol () function may fail if: 

45996 cx [EINVAL] No conversion could be performed. 

45997 EXAMPLES 

45998 None. 

45999 APPLICATION USAGE 

46000 None. 

46001 RATIONALE 

46002 None. 

46003 FUTURE DIRECTIONS 

46004 None. 

46005 SEE ALSO 

46006 iszvalphaO, scanfO, wcstod() , the System Interface Definitions volume of IEEEStd. 1003.1-200x, 

46007 <wchar.h> 

46008 CHANGE HISTORY 

46009 First released in Issue 4. 

46010 Derived from the MSE working draft. 

46011 Issue 5 

46012 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 

46013 Issue 6 

46014 Extensions beyond the ISO C standard are now marked. 

46015 The following new requirements on POSIX implementations derive from alignment with the 

46016 Single UNIX Specification: 

46017 • In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 

46018 added if no conversion could be performed. 
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46019 NAME 

46020 wcstombs — convert a wide-character string to a character string 

46021 SYNOPSIS 

46022 #include <stdlib.h> 

46023 size_t wcstombs (char *s, const wchar_t *pwcs, size_t n) ; 

46024 DESCRIPTION 

46025 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

46026 conflict between the requirements described here and the ISO C standard is unintentional. This I 

46027 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

46028 The wcstombs() function shall convert the sequence of wide-character codes that are in the array 

46029 pointed to by pzvcs into a sequence of characters that begins in the initial shift state and stores 

46030 these characters into the array pointed to by s, stopping if a character would exceed the limit of n 

46031 total bytes or if a null byte is stored. Each wide-character code is converted as if by a call to 

46032 wctomb( ), except that the shift state of wctomb( ) is not affected. 

46033 The behavior of this function shall be affected by the LC_CTYPE category of the current locale. 

46034 No more than n bytes shall be modified in the array pointed to by s. If copying takes place 

46035 cx between objects that overlap, the behavior is undefined. If s is a null pointer, wcstombsO shall 

46036 return the length required to convert the entire array regardless of the value of n, but no values 

46037 are stored. 

46038 The wcstombsO function need not be reentrant. A function that is not required to be reentrant is 

46039 not required to be thread-safe. 

46040 RETURN VALUE 

46041 If a wide-character code is encountered that does not correspond to a valid character (of one or 

46042 more bytes each), wcstovibsO shall return (size_t)-l. Otherwise, wcstombsO shall return the 

46043 number of bytes stored in the character array, not including any terminating null byte. The array 

46044 shall not be null-terminated if the value returned is n. 

46045 ERRORS 

46046 The wcstombs () function may fail if: 

46047 cx [EILSEQ] A wide-character code does not correspond to a valid character. 

46048 EXAMPLES 

46049 None. 

46050 APPLICATION USAGE 

46051 None. 

46052 RATIONALE 

46053 None. 

46054 FUTURE DIRECTIONS 

46055 None. 

46056 SEE ALSO 

46057 mblenO, mbtowcO, mbstowcsO, wctombO, the System Interface Definitions volume of 

46058 IEEE Std. 1003.1-200x, <stdlib.h> 

46059 CHANGE HISTORY 

46060 First released in Issue 4. 

46061 Derived from the ISO C standard. 
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46062 

46063 

46064 

46065 

46066 


Issue 6 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The DESCRIPTION states the effect of when s is a null pointer. 

• The [EILSEQ] error condition is added. 
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46067 NAME 

46068 wcstoul — convert a wide-character string to an unsigned long 

46069 SYNOPSIS 

46070 #include <wchar.h> 

46071 unsigned long int wcstoul (const wchar_t *nptr, wchar_t **endptr, 

46072 int base) ; 

46073 DESCRIPTION 

46074 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

46075 conflict between the requirements described here and the ISO C standard is unintentional. This I 

46076 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

46077 The zvcstoul () function shall convert the initial portion of the wide-character string pointed to by 

46078 nptr to unsigned long int representation. First it decomposes the input wide-character string 

46079 into three parts: 

46080 1. An initial, possibly empty, sequence of white-space wide-character codes (as specified by 

46081 iswspace ()) 

46082 2. A subject sequence interpreted as an integer represented in some radix determined by the 

46083 value of base 

46084 3. A final wide-character string of one or more unrecognized wide-character codes, including 

46085 the terminating null wide-character code of the input wide-character string 

46086 Then it attempts to convert the subject sequence to an unsigned integer, and returns the result. 

46087 If base is 0, the expected form of the subject sequence is that of a decimal constant, octal constant, 

46088 or hexadecimal constant, any of which may be preceded by a ' + ' or sign. A decimal 

46089 constant begins with a non-zero digit, and consists of a sequence of decimal digits. An octal 

46090 constant consists of the prefix ' 0' optionally followed by a sequence of the digits 'O' to ' 7' 

46091 only. A hexadecimal constant consists of the prefix "Ox" or "OX" followed by a sequence of the 

46092 decimal digits and letters ' a' (or ' A') to ' f' (or ' F') with values 10 to 15 respectively. 

46093 If the value of base is between 2 and 36, the expected form of the subject sequence is a sequence 

46094 of letters and digits representing an integer with the radix specified by base, optionally preceded 

46095 by a ' + ' or ' sign, but not including an integer suffix. The letters from ' a' (or ' A') to ' z' 

46096 (or ' Z') inclusive are ascribed the values 10 to 35; only letters whose ascribed values are less 

46097 than that of base are permitted. If the value of base is 16, the wide-character codes "Ox" or "OX" 

46098 may optionally precede the sequence of letters and digits, following the sign if present. 

46099 The subject sequence is defined as the longest initial subsequence of the input wide-character 

46100 string, starting with the first wide-character code that is not white space and is of the expected 

46101 form. The subject sequence contains no wide-character codes if the input wide-character string is 

46102 empty or consists entirely of white-space wide-character codes, or if the first wide-character 

46103 code that is not white space is other than a sign or a permissible letter or digit. 

46104 If the subject sequence has the expected form and base is 0, the sequence of wide-character codes 

46105 starting with the first digit is interpreted as an integer constant. If the subject sequence has the 

46106 expected form and the value of base is between 2 and 36, it is used as the base for conversion, 

46107 ascribing to each letter its value as given above. If the subject sequence begins with a minus sign, 

46108 the value resulting from the conversion is negated. A pointer to the final wide-character string is 

46109 stored in the object pointed to by endptr, provided that endptr is not a null pointer. 

46110 cx In other than the C or POSIX locales, other implementation-dependent subject sequences may be 

46111 accepted. 


1516 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


wcstoulO 


46112 

46113 

46114 

46115 

46116 

46117 

46118 

46119 

46120 

46121 

46122 

46123 

46124 

46125 

46126 

46127 

46128 

46129 

46130 

46131 

46132 

46133 

46134 

46135 

46136 

46137 

46138 

46139 

46140 

46141 

46142 

46143 

46144 

46145 

46146 

46147 

46148 

46149 

46150 

46151 

46152 


If the subject sequence is empty or does not have the expected form, no conversion is performed; 
the value of nptr is stored in the object pointed to by endptr, provided that endptr is not a null 
pointer. 

The zvcstoul () function shall not change the setting of errno if successful. 

Because 0 and |ULONG_MAX} are returned on error and 0 is also a valid return on success, an 
application wishing to check for error situations should set errno to 0, then call wcstonl (), then 
check errno. 

RETURN VALUE 

Upon successful completion, wcstonl () shall return the converted value, if any. If no conversion 
cx could be performed, 0 shall be returned and errno may be set to indicate the error. If the correct 

value is outside the range of representable values, |ULONG_MAX} shall be returned and errno 
set to [ERANGE], 

ERRORS 

The wcstoul{ ) function shall fail if: 
cx [EINVAL] The value of base is not supported. 

[ERANGE] The value to be returned is not representable. 

The wcstoul() function may fail if: 
cx [EINVAL] No conversion could be performed. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

iswalphaOf scanfi ), wcstodO, wcstolO, the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <wchar.h> 

CHANGE HISTORY 

First released in Issue 4. 

Derived from the MSE working draft. 

Issue 5 

The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 

Issue 6 

Extensions beyond the ISO C standard are now marked. 

The following new requirements on POSIX implementations derive from alignment with the 
Single UNIX Specification: 

• The [EINVAL] error condition is added for when the value of base is not supported. 

In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 
added if no conversion could be performed. 
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46153 

46154 

46155 

46156 

46157 

46158 

46159 

46160 

46161 

46162 

46163 

46164 

46165 

46166 

46167 

46168 

46169 

46170 

46171 

46172 

46173 

46174 

46175 

46176 

46177 

46178 

46179 

46180 

46181 

46182 

46183 

46184 

46185 

46186 


NAME 

wcswcs — find a wide substring (LEGACY) 

SYNOPSIS 

xsi tinclude <wchar.h> 

wchar_t *wcswcs(const wchar_t *wsl, const wchar_t *ws2 ); 

DESCRIPTION 

The zvcszvcs() function shall locate the first occurrence in the wide-character string pointed to by 
zvsl of the sequence of wide-character codes (excluding the terminating null wide-character 
code) in the wide-character string pointed to by zvs2. 

RETURN VALUE 

Upon successful completion, zvcszvcs () shall return a pointer to the located wide-character string 
or a null pointer if the wide-character string is not found. 

If zvs2 points to a wide-character string with zero length, the function shall return zvsl. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

This function was not included in the final ISO/IEC 9899:1990/Amendment 1:1995 (E). 
Application developers are strongly encouraged to use the zvcsstr () function instead. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

This function may be withdrawn in a future version. 

SEE ALSO 

zvcschr (), zvcsstr (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

CHANGE HISTORY 

First released in Issue 4. 

Derived from the MSE working draft. 

Issue 5 

Marked EX. 

Issue 6 

This function is marked LEGACY. 
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46187 NAME 

46188 wcswidth — number of column positions of a wide-character string 

46189 SYNOPSIS 

46190 xsi #include <wchar.h> 

46191 int wcswidth (const wchar_t *pwcs, size_t n) ; 

46192 

46193 DESCRIPTION 

46194 The zvcsividth () function shall determine the number of column positions required for n wide- 

46195 character codes (or fewer than n wide-character codes if a null wide-character code is 

46196 encountered before n wide-character codes are exhausted) in the string pointed to by pzvcs. 

46197 RETURN VALUE 

46198 The zvcsividth () function either shall return 0 (if pzvcs points to a null wide-character code), or 

46199 return the number of column positions to be occupied by the wide-character string pointed to by 

46200 pzvcs, or return -1 (if any of the first n wide-character codes in the wide-character string pointed 

46201 to by pzvcs is not a printing wide-character code). 

46202 ERRORS 

46203 No errors are defined. 

46204 EXAMPLES 

46205 None. 

46206 APPLICATION USAGE 

46207 This function was removed from the final ISO/IEC 9899:1990/Amendment 1:1995 (E), and the 

46208 return value for a non-printable wide character is not specified. 

46209 RATIONALE 

46210 None. 

46211 FUTURE DIRECTIONS 

46212 None. 

46213 SEE ALSO 

46214 zvczvidth (), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <wchar.h>, the I 

46215 System Interface Definitions volume of IEEE Std. 1003.1-200x, Section 3.106, Column Position I 

46216 CHANGE HISTORY 

46217 First released in Issue 4. 

46218 Derived from the MSE working draft. 

46219 Issue 6 

46220 The Open Group corrigenda item U021/11 has been applied. The function is marked as an 

46221 extension. 
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46222 NAME 

46223 wcsxfrm — wide-character string transformation 

46224 SYNOPSIS 

46225 tinclude <wchar.h> 

46226 size_t wcsxfrm (wchar_t *wsl, const wchar_t *ws2, size_t n) ; 

46227 DESCRIPTION 

46228 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

46229 conflict between the requirements described here and the ISO C standard is unintentional. This I 

46230 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

46231 The wcsxfrm () function shall transform the wide-character string pointed to by zvs2 and place the 

46232 resulting wide-character string into the array pointed to by wsl . The transformation is such that 

46233 if zvcscmp( ) is applied to two transformed wide strings, it returns a value greater than, equal to, 

46234 or less than 0, corresponding to the result of zvcscoll () applied to the same two original wide- 

46235 character strings. No more than n wide-character codes are placed into the resulting array 

46236 pointed to by zvsl , including the terminating null wide-character code. If n is 0, zvsl is permitted 

46237 to be a null pointer. If copying takes place between objects that overlap, the behavior is 

46238 undefined. 

46239 cx The zvcsxfrm( ) function shall not change the setting of errno if successful. 

46240 Because no return value is reserved to indicate an error, an application wishing to check for error 

46241 situations should set errno to 0, then call zvcsxfrm( ), then check errno. 

46242 RETURN VALUE 

46243 The zvcsxfrm () function shall return the length of the transformed wide-character string (not 

46244 including the terminating null wide-character code). If the value returned is n or more, the 

46245 contents of the array pointed to by zvsl are indeterminate. 

46246 On error, the zvcsxfrm () function may set errno, but no return value is reserved to indicate an 

46247 error. 

46248 ERRORS 

46249 The zvcsxfrm () function may fail if: 

46250 cx [EINVAL] The wide-character string pointed to by zvs2 contains wide-character codes 

46251 outside the domain of the collating sequence. 

46252 EXAMPLES 

46253 None. 

46254 APPLICATION USAGE 

46255 The transformation function is such that two transformed wide-character strings can be ordered 

46256 by wcscmp( ) as appropriate to collating sequence information in the program's locale (category 

46257 LCjCOLLATE). 

46258 The fact that when n is 0 zvsl is permitted to be a null pointer is useful to determine the size of 

46259 the zvsl array prior to making the transformation. 

46260 RATIONALE 

46261 None. 

46262 FUTURE DIRECTIONS 

46263 None. 
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46264 SEE ALSO 

46265 wcscmp (), ivcscoll(), the System Interface Definitions volume of IEEEStd. 1003.l-200x, 

46266 <wchar.h> 

46267 CHANGE HISTORY 

46268 First released in Issue 4. 

46269 Derived from the MSE working draft. 

46270 Issue 5 

46271 Moved from ENHANCED I18N to BASE and the [ENOSYS] error is removed. 

46272 The DESCRIPTION is updated to indicate that errno is not changed if the function is successful. 

46273 Issue 6 

46274 In previous versions, this function was required to return -1 on error. 

46275 Extensions beyond the ISO C standard are now marked. 

46276 The following new requirements on POSIX implementations derive from alignment with the 

46277 Single UNIX Specification: 

46278 • In the RETURN VALUE and ERRORS sections, the [EINVAL] optional error condition is 

46279 added if no conversion could be performed. 


System Interfaces, Issue 6 


1521 



wctob() 


System Interfaces 


46280 

46281 

46282 

46283 

46284 

46285 

46286 

46287 

46288 

46289 

46290 

46291 

46292 

46293 

46294 

46295 

46296 

46297 

46298 

46299 

46300 

46301 

46302 

46303 

46304 

46305 

46306 

46307 

46308 

46309 
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NAME 

wctob — wide-character to single-byte conversion 

SYNOPSIS 

#include <stdio.h> 

#include <wchar.h> 

int wctob(wint_t c) ; 

DESCRIPTION 

cx The functionality described on this reference page is aligned with the ISO C standard. Any 

conflict between the requirements described here and the ISO C standard is unintentional. This I 
volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

The zvctob() function shall determine whether c corresponds to a member of the extended 
character set whose character representation is a single byte when in the initial shift state. 

The behavior of this function shall be affected by the LC_CTYPE category of the current locale. 

RETURN VALUE 

The wctob() function shall return EOF if c does not correspond to a character with length one in 
the initial shift state. Otherwise, it shall return the single-byte representation of that character. 

ERRORS 

No errors are defined. 

EXAMPLES 

None. 

APPLICATION USAGE 

None. 

RATIONALE 

None. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

btozvc (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

CHANGE HISTORY 

First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 
(E). I 


1522 


Technical Standard (2000) (Draft February 29, 2000) 



System Interfaces 


wctomb() 


46311 NAME 

46312 wctomb — convert a wide-character code to a character 

46313 SYNOPSIS 

46314 #include <stdlib.h> 

46315 int wctomb (char *s, wchar_t wchar) ; 

46316 DESCRIPTION 

46317 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

46318 conflict between the requirements described here and the ISO C standard is unintentional. This I 

46319 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

46320 The wctomb() function shall determine the number of bytes needed to represent the character 

46321 corresponding to the wide-character code whose value is wchar (including any change in the 

46322 shift state). It stores the character representation (possibly multiple bytes and any special bytes 

46323 to change shift state) in the array object pointed to by s (if s is not a null pointer). At most 

46324 |MB_CUR_MAX} bytes are stored. If wchar is 0, zvctomb( ) is left in the initial shift state. 

46325 cx The behavior of this function is affected by the LC_CTYPE category of the current locale. For a 

46326 state-dependent encoding, this function is placed into its initial state by a call for which its 

46327 character pointer argument, s, is a null pointer. Subsequent calls with s as other than a null 

46328 pointer cause the internal state of the function to be altered as necessary. A call with s as a null 

46329 pointer causes this function to return a non-zero value if encodings have state dependency, and 

46330 0 otherwise. Changing the LC_CTYPE category causes the shift state of this function to be 

46331 indeterminate. 

46332 The zvctomb( ) function need not be reentrant. A function that is not required to be reentrant is 

46333 not required to be thread-safe. 

46334 The implementation shall behave as if no function defined in this volume of 

46335 IEEE Std. 1003.1-200x calls zvctomb( ). 

46336 RETURN VALUE 

46337 If s is a null pointer, zvctomb() shall return a non-zero or 0 value, if character encodings, 

46338 respectively, do or do not have state-dependent encodings. If s is not a null pointer, zvctomb() 

46339 shall return -1 if the value of wchar does not correspond to a valid character, or return the 

46340 number of bytes that constitute the character corresponding to the value of zvchar. 

46341 In no case shall the value returned be greater than the value of the {MB_CUR_MAX} macro. 

46342 ERRORS 

46343 No errors are defined. 

46344 EXAMPLES 

46345 None. 

46346 APPLICATION USAGE 

46347 None. 

46348 RATIONALE 

46349 None. 

46350 FUTURE DIRECTIONS 

46351 None. 
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46352 SEE ALSO 

46353 mb ten (), mbtozvc(), mbstowcs (), wcstombs(), the System Interface Definitions volume of 

46354 IEEE Std. 1003.1-200x, <stdlib.h> 

46355 CHANGE HISTORY 

46356 First released in Issue 4. 

46357 Derived from the ANSI C standard. 

46358 Issue 6 

46359 Extensions beyond the ISO C standard are now marked. 

46360 In the DESCRIPTION, a note about reentrancy and thread-safety is added. 
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46361 NAME 

46362 wctrans — define character mapping 

46363 SYNOPSIS 

46364 #include <wctype.h> 

46365 wctrans_t wctrans (const char *charclass) ; 

46366 DESCRIPTION 

46367 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

46368 conflict between the requirements described here and the ISO C standard is unintentional. This I 

46369 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

46370 The wctrans () function is defined for valid character mapping names identified in the current 

46371 locale. The charclass is a string identifying a generic character mapping name for which codeset- 

46372 specific information is required. The following character mapping names are defined in all 

46373 locales: tolower and toupper. 

46374 The function shall return a value of type wctrans_t, which can be used as the second argument 

46375 to subsequent calls of towctrans{). The ivctrans() function determines values of wctrans_t 

46376 according to the rules of the coded character set defined by character mapping information in 

46377 the program's locale (category LCJCTYPE). The values returned by wctrans() are valid until a 

46378 call to setlocale() that modifies the category LCJCTYPE. 

46379 RETURN VALUE 

46380 cx The wctrans () function shall return 0 and may set errno to indicate the error if the given character 

46381 mapping name is not valid for the current locale (category LCJCTYPE)-, otherwise, it shall return 

46382 a non-zero object of type wctrans_t that can be used in calls to tozvctrans (). 

46383 ERRORS 

46384 The zvctrans( ) function may fail if: 

46385 cx [EINVAL] The character mapping name pointed to by charclass is not valid in the current 

46386 locale. 

46387 EXAMPLES 

46388 None. 

46389 APPLICATION USAGE 

46390 None. 

46391 RATIONALE 

46392 None. 

46393 FUTURE DIRECTIONS 

46394 None. 

46395 SEE ALSO 

46396 towctrans (), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wctype.h> 

46397 CHANGE HISTORY 

46398 First released in Issue 5. 

46399 Derived from ISO/IEC 9899:1990/Amendment 1:1995 (E). 
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46400 NAME 

46401 wctype — define character class 

46402 SYNOPSIS 

46403 #include <wctype.h> 

46404 wctype_t wctype (const char * property) ; 

46405 DESCRIPTION 

46406 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

46407 conflict between the requirements described here and the ISO C standard is unintentional. This I 

46408 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

46409 The zvctype( ) function is defined for valid character class names as defined in the current locale. 

46410 The property is a string identifying a generic character class for which codeset-specific type 

46411 information is required. The following character class names are defined in all locales: 


46412 

alnum 

digit 

punct 

46413 

alpha 

graph 

space 

46414 

blank 

lower 

upper 

46415 

cntrl 

print 

xdigit 


46416 Additional character class names defined in the locale definition file (category LC_CTYPE) can 

46417 also be specified. 

46418 The function shall return a value of type wctype_t, which can be used as the second argument to 

46419 subsequent calls of isiuctype( ). The wctype() function determines values of wctype_t according 

46420 to the rules of the coded character set defined by character type information in the program's 

46421 locale (category LC_CTYPE). The values returned by zvctype( ) are valid until a call to setlocale () 

46422 that modifies the category LC_CTYPE. 

46423 RETURN VALUE 

46424 The zvctype( ) function shall return 0 if the given character class name is not valid for the current 

46425 locale (category LC_CTYPE); otherwise, it shall return an object of type wctype_t that can be 

46426 used in calls to iszvctype(). 

46427 ERRORS 

46428 No errors are defined. 

46429 EXAMPLES 

46430 None. 

46431 APPLICATION USAGE 

46432 None. 

46433 RATIONALE 

46434 None. 

46435 FUTURE DIRECTIONS 

46436 None. 

46437 SEE ALSO 

46438 iszvctype(), the System Interface Definitions volume of IEEE Std. 1003.l-200x, <wctype.h>, 

46439 <wchar.h> 

46440 CHANGE HISTORY 

46441 First released in Issue 4. 
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46442 

46443 

46444 

46445 

46446 


Issue 5 

The following change has been made in this issue for alignment with 
ISO/IEC 9899:1990/Amendment 1:1995 (E): 

• The SYNOPSIS has been changed to indicate that this function and associated data types are 
now made visible by inclusion of the header <wctype.h> rather than <wchar.h>. 
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46447 NAME 

46448 wcwidth — number of column positions of a wide-character code 

46449 SYNOPSIS 

46450 xsi #include <wchar.h> 

46451 int wcwidth (wchar_t wc) ; 

46452 

46453 DESCRIPTION 

46454 The zvczvidth () function shall determine the number of column positions required for the wide I 

46455 character zvc. The application shall ensure that the value of zvc is a character representable as a I 

46456 wchar_t, and a wide-character code corresponding to a valid character in the current locale. I 

46457 RETURN VALUE 

46458 The zvczvidth () function shall either return 0 (if zvc is a null wide-character code), or return the 

46459 number of column positions to be occupied by the wide-character code zvc, or return -1 (if zvc 

46460 does not correspond to a printing wide-character code). 

46461 ERRORS 

46462 No errors are defined. 

46463 EXAMPLES 

46464 None. 

46465 APPLICATION USAGE 

46466 This function was removed from the final ISO/IEC 9899:1990/Amendment 1:1995 (E), and the 

46467 return value for a non-printable wide character is not specified. 

46468 RATIONALE 

46469 None. 

46470 FUTURE DIRECTIONS 

46471 None. 

46472 SEE ALSO 

46473 zvcszvidth( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <wchar.h> 

46474 CHANGE HISTORY 

46475 First released as a World-wide Portability Interface in Issue 4. 

46476 Derived from MSE working draft. 

46477 Issue 6 

46478 The Open Group corrigenda item U021/12 has been applied. This function is marked as an 

46479 extension. I 

46480 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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46481 NAME 

46482 wmemchr — find a wide character in memory 

46483 SYNOPSIS 

46484 #include <wchar.h> 

46485 wchar_t *wmemchr (const wchar_t *ws, wchar_t wc, size_t n) ; 

46486 DESCRIPTION 

46487 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

46488 conflict between the requirements described here and the ISO C standard is unintentional. This I 

46489 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

46490 The wmemchr( ) function shall locate the first occurrence of zvc in the initial n wide characters of 

46491 the object pointed to by zvs. This function is not affected by locale and all wchar_t values are 

46492 treated identically. The null wide character and wchar_t values not corresponding to valid 

46493 characters are not treated specially. 

46494 If n is zero, the application shall ensure that zvs is a valid pointer and the function behaves as if I 

46495 no valid occurrence of zvc is found. I 

46496 RETURN VALUE 

46497 The zvmemchr( ) function shall return a pointer to the located wide character, or a null pointer if 

46498 the wide character does not occur in the object. 

46499 ERRORS 

46500 No errors are defined. 

46501 EXAMPLES 

46502 None. 

46503 APPLICATION USAGE 

46504 None. 

46505 RATIONALE 

46506 None. 

46507 FUTURE DIRECTIONS 

46508 None. 

46509 SEE ALSO 

46510 zvmemcmp (), zvmemcpy(), zvmemmove (), wmemset(), the System Interface Definitions volume of 

46511 IEEE Std. 1003.1-200x, <wchar.h> 

46512 CHANGE HISTORY 

46513 First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 

46514 (E). I 

46515 Issue 6 I 

46516 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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46517 NAME 

46518 wmemcmp — compare wide characters in memory 

46519 SYNOPSIS 

46520 #include <wchar.h> 

46521 int wmemcmp (const wchar_t *wsl, const wchar_t *ws2, size_t n) ; 

46522 DESCRIPTION 

46523 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

46524 conflict between the requirements described here and the ISO C standard is unintentional. This I 

46525 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

46526 The wmemcmp () function shall compare the first n wide characters of the object pointed to by 

46527 zvsl to the first n wide characters of the object pointed to by zvs2 . This function is not affected by 

46528 locale and all wchar_t values are treated identically. The null wide character and wchar_t values 

46529 not corresponding to valid characters are not treated specially. 

46530 If n is zero, the application shall ensure that zvsl and zvs2 are valid pointers, and the function I 

46531 behaves as if the two objects compare equal. I 

46532 RETURN VALUE 

46533 The wmemcmp () function shall return an integer greater than, equal to, or less than zero, 

46534 respectively, as the object pointed to by zvsl is greater than, equal to, or less than the object 

46535 pointed to by zvs2. 

46536 ERRORS 

46537 No errors are defined. 

46538 EXAMPLES 

46539 None. 

46540 APPLICATION USAGE 

46541 None. 

46542 RATIONALE 

46543 None. 

46544 FUTURE DIRECTIONS 

46545 None. 

46546 SEE ALSO 

46547 wmemchr(), wmemcpy{), wmemmove(), wmemset{ ), the System Interface Definitions volume of 

46548 IEEE Std. 1003.1-200x, <wchar.h> 

46549 CHANGE HISTORY 

46550 First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 

46551 (E). I 

46552 Issue 6 I 

46553 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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46554 NAME 

46555 wmemcpy — copy wide characters in memory 

46556 SYNOPSIS 

46557 #include <wchar.h> 

46558 wchar_t *wmemcpy (wchar_t *wsl, const wchar_t *ws2, size_t n) ; 

46559 DESCRIPTION 

46560 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

46561 conflict between the requirements described here and the ISO C standard is unintentional. This I 

46562 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

46563 The ivmemcpy( ) function shall copy n wide characters from the object pointed to by zvs2 to the 

46564 object pointed to by wsl. This function is not affected by locale and all wchar_t values are 

46565 treated identically. The null wide character and wchar_t values not corresponding to valid 

46566 characters are not treated specially. 

46567 If n is zero, the application shall ensure that wsl and ws2 are valid pointers, and the function I 

46568 copies zero wide characters. I 

46569 RETURN VALUE 

46570 The wmemcpy ( ) function shall return the value of wsl. 

46571 ERRORS 

46572 No errors are defined. 

46573 EXAMPLES 

46574 None. 

46575 APPLICATION USAGE 

46576 None. 

46577 RATIONALE 

46578 None. 

46579 FUTURE DIRECTIONS 

46580 None. 

46581 SEE ALSO 

46582 wmemchr( ), lumemcmpi ), wmemmove(), wmemset(), the System Interface Definitions volume of 

46583 IEEE Std. 1003.1-200x, <wchar.h> 

46584 CHANGE HISTORY 

46585 First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 

46586 (E). I 

46587 Issue 6 I 

46588 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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46589 NAME 

46590 wmemmove — copy wide characters in memory with overlapping areas 

46591 SYNOPSIS 

46592 #include <wchar.h> 

46593 wchar_t *wmemmove (wchar_t *wsl, const wchar_t *ws2, size_t n) ; 

46594 DESCRIPTION 

46595 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

46596 conflict between the requirements described here and the ISO C standard is unintentional. This I 

46597 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

46598 The wmemmove( ) function shall copy n wide characters from the object pointed to by zvs2 to the 

46599 object pointed to by zvsl . Copying takes place as if the n wide characters from the object pointed 

46600 to by zvs2 are first copied into a temporary array of n wide characters that does not overlap the 

46601 objects pointed to by zvsl or zvs2, and then the n wide characters from the temporary array are 

46602 copied into the object pointed to by zvsl. 

46603 This function is not affected by locale and all wchar_t values are treated identically. The null 

46604 wide character and wchar_t values not corresponding to valid characters are not treated 

46605 specially. 

46606 If n is zero, the application shall ensure that zvsl and zvs2 are valid pointers, and the function I 

46607 copies zero wide characters. I 

46608 RETURN VALUE 

46609 The zvmemmove( ) function shall return the value of zvsl. 

46610 ERRORS 

46611 No errors are defined 

46612 EXAMPLES 

46613 None. 

46614 APPLICATION USAGE 

46615 None. 

46616 RATIONALE 

46617 None. 

46618 FUTURE DIRECTIONS 

46619 None. 

46620 SEE ALSO 

46621 zvmemchr(), zvmemcmp(), wmemcpy(), zvmemset(), the System Interface Definitions volume of 

46622 IEEE Std. 1003.1-200x, <wchar.h> 

46623 CHANGE HISTORY 

46624 First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 

46625 (E). I 

46626 Issue 6 I 

46627 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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46628 NAME 

46629 wmemset — set wide characters in memory 

46630 SYNOPSIS 

46631 tinclude <wchar.h> 

46632 wchar_t *wmemset (wchar_t *ws, wchar_t wc, size_t n) ; 

46633 DESCRIPTION 

46634 cx The functionality described on this reference page is aligned with the ISO C standard. Any 

46635 conflict between the requirements described here and the ISO C standard is unintentional. This I 

46636 volume of IEEE Std. 1003.1-200x defers to the ISO C standard. I 

46637 The zvmemset{ ) function shall copy the value of wc into each of the first n wide characters of the 

46638 object pointed to by zvs. This function is not affected by locale and all wchar_t values are treated 

46639 identically. The null wide character and wchar_t values not corresponding to valid characters 

46640 are not treated specially. 

46641 If n is zero, the application shall ensure that zvs is a valid pointer, and the function copies zero I 

46642 wide characters. I 

46643 RETURN VALUE 

46644 The zvmemset( ) functions shall return the value of zvs. 

46645 ERRORS 

46646 No errors are defined. 

46647 EXAMPLES 

46648 None. 

46649 APPLICATION USAGE 

46650 None. 

46651 RATIONALE 

46652 None. 

46653 FUTURE DIRECTIONS 

46654 None. 

46655 SEE ALSO 

46656 wmemchr( ), wmemcmp (), wmemcpy{), zvmemmove( ), the System Interface Definitions volume of 

46657 IEEE Std. 1003.1-200x, <wchar.h> 

46658 CHANGE HISTORY 

46659 First released in Issue 5. Included for alignment with ISO/IEC 9899:1990/Amendment 1:1995 I 

46660 (E). I 

46661 Issue 6 I 

46662 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. I 
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NAME 

wordexp, wordfree — perform word expansions 

SYNOPSIS 

#include <wordexp.h> 

int wordexp(const char *words, wordexp_t *pwordexp, int flags); 
void wordfree(wordexp_t * pwordexp) ; 

DESCRIPTION 

The wordexp () function shall perform word expansions and place the list of expanded words I 
into pivordexp. I 

If the implementation supports the utilities defined in the Commands and Utilities volume of I 
IEEE Std. 1003.l-200x, the wordexp () function performs word expansions as described in the I 
Commands and Utilities volume of IEEE Std. 1003.1-200x, Section 2.6, Word Expansions, subject 
to quoting as in the Commands and Utilities volume of IEEE Std. 1003.1-200x, Section 2.2, 
Quoting, and places the list of expanded words into the structure pointed to by pivordexp. 

The ivords argument is a pointer to a string containing one or more words to be expanded. The 
expansions shall be the same as would be performed by the command line interpreter if ivords I 
were the part of a command line representing the arguments to a utility. Therefore, the I 
application shall ensure that words does not contain an unquoted <newline> or any of the I 
unquoted shell special characters ' I', '<', ' >' except in the context of command 

substitution as specified in the Commands and Utilities volume of IEEE Std. 1003.1-200x, Section I 
2.6.3, Command Substitution. It also shall not contain unquoted parentheses or braces, except in I 
the context of command or variable substitution. If the argument words contains an unquoted 
comment character (number sign) that is the beginning of a token, wordexp () shall either treat the I 
comment character as a regular character, or interpret it as a comment indicator and ignore the I 
remainder of words. 

If the implementation does not support the utilities defined in the Commands and Utilities I 
volume of IEEE Std. 1003.1-200x, the word expansion is unspecified, but should be the same as I 
that used by the command language interpreter used by the system () and popen () functions. I 

The structure type wordexp_t is defined in the header <wordexp.h> and includes at least the I 
following members: 


Member Type 

Member Name 

Description 

size_t 
char ** 
size_t 

wejwordc 

wejwordv 

we_offs 

Count of words matched by words. 

Pointer to list of expanded words. 

Slots to reserve at the beginning of pwordexp -^wejwordv. 


The wordexp () function stores the number of generated words into pwordexp^we_wordc and a 
pointer to a list of pointers to words in pwordexp-twepivordv. If the implementation supports the I 
utilities defined in the Commands and Utilities volume of IEEE Std. 1003.1-200x, each individual I 
field created during field splitting (see the Commands and Utilities volume of I 
IEEE Std. 1003.1-200x, Section 2.6.5, Field Splitting) or path name expansion (see the Commands 
and Utilities volume of IEEE Std. 1003.1-200x, Section 2.6.6, Path Name Expansion) is a separate 
word in the pwordexp-^wejwordv list. The words are in order as described in the Commands and 
Utilities volume of IEEE Std. 1003.1-200x, Section 2.6, Word Expansions. The first pointer after 
the last word pointer shall be a null pointer. The expansion of special parameters described in I 
the Commands and Utilities volume of IEEE Std. 1003.1-200x, Section 2.5.2, Special Parameters is I 
unspecified. I 


1534 


Technical Standard (2000) (Draft February 29, 2000) 





System Interfaces 


wordexpO 


46709 

46710 

46711 

46712 

46713 

46714 

46715 

46716 

46717 

46718 

46719 

46720 

46721 

46722 

46723 

46724 

46725 

46726 

46727 

46728 

46729 

46730 

46731 

46732 

46733 

46734 

46735 

46736 

46737 

46738 

46739 

46740 

46741 

46742 

46743 

46744 

46745 

46746 

46747 

46748 

46749 

46750 

46751 


It is the caller's responsibility to allocate the storage pointed to by pzvordexp. The ivordexp () 
function allocates other space as needed, including memory pointed to by pwordexp-^we_wordv. 
The zvordfree() function frees any memory associated with pzvordexp from a previous call to 
zvordexp(). 


The flags argument is used to control the behavior of zoordexp(). The value of flags is the 
bitwise-inclusive OR of zero or more of the following constants, which are defined in 

<wordexp.h>: 


WRDE_APPEND 

WRDE_DOOFFS 


WRDE_NOCMD 


WRDE_REUSE 


Append words generated to the ones from a previous call to zvordexp (). 

Make use of pzvordexp^>zve_offs . If this flag is set, pzvordexp—tzvejoffs is 
used to specify how many null pointers to add to the beginning of 
pzvordexp ^>zve_wordv. In other words, pzvordexp—nve_zvordv shall point to 
pzvordexp-^zve_offs null pointers, followed by pzvordexp-^>zve_zvordc word 
pointers, followed by a null pointer. 

If the implementation supports the utilities defined in the Commands I 
and Utilities volume of IEEE Std. 1003.1-200x, fail if command I 
substitution, as specified in the Commands and Utilities volume of I 
IEEE Std. 1003.1-200x, Section 2.6.3, Command Substitution, is requested. I 

The pzvordexp argument was passed to a previous successful call to 
zvordexp{ ), and has not been passed to zvordfree( ). The result shall be the 
same as if the application had called zvordfree( ) and then called zvordexp () 
without WRDE_REUSE. 


WRDE_SHOWERR Do not redirect stderr to /dev/null. 

WRDE_UNDEF Report error on an attempt to expand an undefined shell variable. 

The WRDE_APPEND flag can be used to append a new set of words to those generated by a 
previous call to zvordexp( ). The following rules apply to applications when two or more calls to I 
zvordexp() are made with the same value of pzvordexp and without intervening calls to zvordfree (): 

1. The first such call shall not set WRDE_APPEND. All subsequent calls shall set it. I 

2. All of the calls shall set WRDE_DOOFFS, or all shall not set it. I 

3. After the second and each subsequent call, pzvordexp-^zve_zvordz’ shall point to a list 
containing the following: 

a. Zero or more null pointers, as specified by WRDE_DOOFFS and pzvordexp^>zve_offs 

b. Pointers to the words that were in the pzvordexp-^zve_zvordz’ list before the call, in the 
same order as before 


c. Pointers to the new words generated by the latest call, in the specified order 

4. The count returned in pzvordexp-^zve_zvordc shall be the total number of words from all of 
the calls. 


5. The application can change any of the fields after a call to zvordexp (), but if it does it shall I 
reset them to the original value before a subsequent call, using the same pzvordexp value, to I 
zvordfree( ) or zvordexp () with the WRDE_APPEND or WRDE_REUSE flag. 

If the implementation supports the utilities defined in the Commands and Utilities volume of I 
IEEE Std. 1003.1-200x, and zvords contains an unquoted character—<newline>, ' | , I 

' —in an inappropriate context, zvordexp () shall fail, and the number 
of expanded words shall be 0. 
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46752 Unless WRDE_SHOWERR is set in flags, zvordexp() shall redirect stderr to /dev/null for any 

46753 utilities executed as a result of command substitution while expanding zvords. If 

46754 WRDE_SHOWERR is set, zvordexp () may write messages to stderr if syntax errors are detected 

46755 while expanding zvords. 

46756 The application shall ensure that if WRDE_DOOFFS is set, then pzvordexp-^zve_offs has the same I 

46757 value for each zvordexp( ) call and zvordfree( ) call using a given pzvordexp. I 

46758 The following constants are defined as error return values: 

46759 WRDE_BADCHAR One of the unquoted characters—<newline>, ' | ', ' <', '>', 

46760 ' —appears in zvords in an inappropriate context. 

46761 WRDE_BADVAL Reference to undefined shell variable when WRDE_UNDEF is set in flags. 

46762 WRDE_CMDSUB Command substitution requested when WRDE_NOCMD was set in flags. 

46763 WRDE_NOSPACE Attempt to allocate memory failed. 

46764 WRDE_SYNTAX Shell syntax error, such as unbalanced parentheses or unterminated 

46765 String. 

46766 RETURN VALUE 

46767 Upon successful completion, zvordexp () shall return 0. Otherwise, a non-zero value, as described I 

46768 in <wordexp.h>, shall be returned to indicate an error. If zvordexp () returns the value 

46769 WRDE_NOSPACE, then pzvordexp->zve_zvordc and pzvordexp^>zve_zvordv shall be updated to 

46770 reflect any words that were successfully expanded. In other cases, they shall not be modified. 

46771 The zvordfree( ) function shall return no value. 

46772 ERRORS 

46773 No errors are defined. 

46774 EXAMPLES 

46775 None. 

46776 APPLICATION USAGE 

46777 The zvordexp () function is intended to be used by an application that wants to do all of the shell's 

46778 expansions on a word or words obtained from a user. For example, if the application prompts 

46779 for a file name (or list of file names) and then uses zvordexp () to process the input, the user could 

46780 respond with anything that would be valid as input to the shell. 

46781 The WRDE_NOCMD flag is provided for applications that, for security or other reasons, want to 

46782 prevent a user from executing shell commands. Disallowing unquoted shell special characters 

46783 also prevents unwanted side effects, such as executing a command or writing a file. 

46784 RATIONALE 

46785 This function was included as an alternative to glob(). There had been continuing controversy 

46786 over exactly what features should be included in glob( ). It is hoped that by providing zvordexp () 

46787 (which provides all of the shell word expansions, but which may be slow to execute) and glob() 

46788 (which is faster, but which only performs path name expansion, without tilde or parameter 

46789 expansion) this will satisfy the majority of applications. 

46790 While zvordexp () could be implemented entirely as a library routine, it is expected that most 

46791 implementations run a shell in a subprocess to do the expansion. 

46792 Two different approaches have been proposed for how the required information might be 

46793 presented to the shell and the results returned. They are presented here as examples. 

46794 One proposal is to extend the echo utility by adding a -q option. This option would cause echo to 

46795 add a backslash before each backslash and <blank> character that occurs within an argument. 
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The zvordexp( ) function could then invoke the shell as follows: 

(void) strcpy (buffer, "echo -q"); 

(void) strcat (buffer, words) ; 
if ((flags & WRDE_SHOWERR) == 0) 

(void) strcat (buffer, "2>/dev/null"); 
f = popen (buffer, "r"); 

The wordexpO function would read the resulting output, remove unquoted backslashes, and 
break into words at unquoted <blank>s. If the WRDE_NOCMD flag was set, wordexpO would 
have to scan zvords before starting the subshell to make sure that there would be no command 
substitution. In any case, it would have to scan zvords for unquoted special characters. 

Another proposal is to add the following options to sh: 

-w zvordlist 

This option provides a wordlist expansion service to applications. The words in zvordlist 
shall be expanded and the following written to standard output: 

1. The count of the number of words after expansion, in decimal, followed by a null byte 

2. The number of bytes needed to represent the expanded words (not including null 
separators), in decimal, followed by a null byte 

3. The expanded words, each terminated by a null byte 

If an error is encountered during word expansion, sh exits with a non-zero status after 
writing the former to report any words successfully expanded 

-P Run in "protected” mode. If specified with the -w option, no command substitution shall 
be performed. 

With these options, zvordexpO could be implemented fairly simply by creating a subprocess 
using fork( ) and executing sh using the line: 

execl {<shell path>, "sh", "-P", "-w", words, (char *)0); 

after directing standard error to /dev/null. 

It seemed objectionable for a library routine to write messages to standard error, unless 
explicitly requested, so zvordexpO is required to redirect standard error to /dev/null to ensure 
that no messages are generated, even for commands executed for command substitution. The 
WRDE_SHOWERR flag can be specified to request that error messages be written. 

The WRDE_REUSE flag allows the implementation to avoid the expense of freeing and 
reallocating memory, if that is possible. A minimal implementation can call wordfreeO when 
WRDE_REUSE is set. 

FUTURE DIRECTIONS 

None. 

SEE ALSO 

fnmatchO , glob( ), the System Interface Definitions volume of IEEE Std. 1003.l-200x, 
<wordexp.h>, the Commands and Utilities volume of IEEE Std. 1003.1-200x 

CHANGE HISTORY 

First released in Issue 4. 

Derived from the ISO POSIX-2 standard. 
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46837 Issue 5 

46838 Moved from POSIX2 C-language Binding to BASE. 

46839 Issue 6 

46840 The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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46841 NAME 

46842 wprintf — print formatted wide-character output 

46843 SYNOPSIS 

46844 #include <stdio.h> 

46845 #include <wchar.h> 

46846 int wprintf (const wchar_t * format, . . . ) ; 

46847 DESCRIPTION 

46848 Refer to fivprin tf (). 
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NAME 

pwrite, write, writev — write on a file 

Notes to Reviewers 

This section with side shading will not appear in the final copy. - Ed. 

This function or these functions are recommended to become mandatory parts of POSIX.l in the 
next draft. 

SYNOPSIS 

#include <unistd.h> 

xsi ssize_t pwrite (int fildes, const void *buf, size_t nbyte, 

off_t offset); 

ssize_t write (int fildes, const void *buf, size_t nbyte); 
xsi tinclude <sys/uio.h> 

ssize_t writev(int fildes, const struct iovec *iov, int iovcnt) ; 


DESCRIPTION 

xsi The pwrite () function performs the same action as ivrite(), except that it writes into a given 
position without changing the file pointer. The first three arguments to pwrite{) are the same as 
write{ ) with the addition of a fourth argument offset for the desired position inside the file. 

The write{) function shall attempt to write nbyte bytes from the buffer pointed to by buf to the 
file associated with the open file descriptor, fildes. 

If nbyte is zero and the file is a regular file, the ivrite( ) function may detect and return errors as I 
described below. In the absence of errors, or if error detection is not performed, the write{) I 
function shall return zero and have no other results. If nbyte is zero and the file is not a regular I 
file, the results are unspecified. I 

On a regular file or other file capable of seeking, the actual writing of data proceeds from the 
position in the file indicated by the file offset associated with fildes. Before successful return 
from ivrite( ), the file offset is incremented by the number of bytes actually written. On a regular 
file, if this incremented file offset is greater than the length of the file, the length of the file shall 
be set to this file offset. 

On a file not capable of seeking, writing always takes place starting at the current position. The 
value of a file offset associated with such a device is undefined. 

If the 0_APPEND flag of the file status flags is set, the file offset shall be set to the end of the file 
prior to each write and no intervening file modification operation shall occur between changing 
the file offset and the write operation. 

xsi If a write{ ) requests that more bytes be written than there is room for (for example, the process' 
file size limit or the physical end of a medium), only as many bytes as there is room for shall be 
written. For example, suppose there is space for 20 bytes more in a file before reaching a limit. A 
write of 512 bytes shall return 20. The next write of a non-zero number of bytes shall give a 
xsi failure return (except as noted below) and the implementation shall generate a SIGXFSZ signal 
for the thread. 

If write() is interrupted by a signal before it writes any data, it shall eturn -1 with errno set to 
[EINTR], 

If write( ) is interrupted by a signal after it successfully writes some data, it shall return the 
number of bytes written. 
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If the value of nbyte is greater than {SSIZE_MAX}, the result is implementation-dependent. 

After a write( ) to a regular file has successfully returned: 

• Any successful read() from each byte position in the file that was modified by that write shall 
return the data specified by the ivrite( ) for that position until such byte positions are again 
modified. 

• Any subsequent successful write{ ) to the same byte position in the file shall overwrite that 
file data. 

Write requests to a pipe or FIFO shall be handled the same as a regular file with the following 
exceptions: 

• There is no file offset associated with a pipe, hence each write request shall append to the 
end of the pipe. 

• Write requests of |PIPE_BUF} bytes or less shall not be interleaved with data from other 
processes doing writes on the same pipe. Writes of greater than {PIPE_BUF} bytes may have 
data interleaved, on arbitrary boundaries, with writes by other processes, whether or not the 
0_NONBEOCK flag of the file status flags is set. 

• If the 0_NONBEOCK flag is clear, a write request may cause the thread to block, but on 
normal completion it shall return nbyte. 

• If the 0_NONBEOCK flag is set, zvrite() requests shall be handled differently, in the 
following ways: 

man — The ivrite( ) function shall not block the thread. 

— A write request for |PIPE_BUF} or fewer bytes shall have the following effect: if there is 
sufficient space available in the pipe, write( ) shall transfer all the data and return the 
number of bytes requested. Otherwise, write( ) shall transfer no data and return -1 with 
errno set to [EAGAIN]. 

— A write request for more than {PIPE_BUF} bytes shall cause one of the following: 

— When at least one byte can be written, transfer what it can and return the number of 
bytes written. When all data previously written to the pipe is read, it shall transfer at 
least |PIPE_BUF} bytes. 

— When no data can be written, transfer no data, and return -1 with errno set to 
[EAGAIN], 

When attempting to write to a file descriptor (other than a pipe or FIFO) that supports non- 
blocking writes and cannot accept the data immediately: 

• If the 0_NONBFOCK flag is clear, write( ) shall block the calling thread until the data can be 
accepted. 

man • If the 0_NONBFOCK flag is set, zvrite() shall not block the thread. If some data can be 

man written without blocking the thread, write( ) shall write what it can and return the number of 

bytes written. Otherwise, it shall return -1 and set errno to [EAGAIN]. 

Upon successful completion, where nbyte is greater than 0, write () shall mark for update the 
stjctime and s tjntime fields of the file, and if the file is a regular file, the S_ISUID and S_ISGID 
bits of the file mode may be cleared. 

xsr If fildes refers to a STREAM, the operation of zvrite() shall be determined by the values of the 
minimum and maximum nbyte range (packet size) accepted by the STREAM. These values are 
determined by the topmost STREAM module. If nbyte falls within the packet size range, nbyte 
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bytes shall be written. If nbyte does not fall within the range and the minimum packet size value 
is 0, write( ) shall break the buffer into maximum packet size segments prior to sending the data 
downstream (the last segment may contain less than the maximum packet size). If nbyte does not 
fall within the range and the minimum value is non-zero, write() shall fail with errno set to 
[ERANGE], Writing a zero-length buffer ( nbyte is 0) to a STREAMS device sends 0 bytes with 0 
returned. However, writing a zero-length buffer to a STREAMS-based pipe or FIFO sends no 
message and 0 is returned. The process may issue I_SWROPT ioctl() to enable zero-length 
messages to be sent across the pipe or FIFO. 

When writing to a STREAM, data messages are created with a priority band of 0. When writing 
to a STREAM that is not a pipe or FIFO: 

• If 0_NONBLOCK is clear, and the STREAM cannot accept data (the STREAM write queue is 
full due to internal flow control conditions), ivrite( ) shall block until data can be accepted. 

• If 0_NONBLOCK is set and the STREAM cannot accept data, write ( ) shall return -1 and set 
errno to [EAGAIN]. 

• If 0_NONBLOCK is set and part of the buffer has been written while a condition in which 
the STREAM cannot accept additional data occurs, ivrite( ) shall terminate and return the 
number of bytes written. 

In addition, zvrite() and writev{) shall fail if the STREAM head has processed an asynchronous 
error before the call. In this case, the value of errno does not reflect the result of zvrite() or 
ivritev( ), but reflects the prior error. I 

xsi The writev( ) function is equivalent to write( ), but gathers the output data from the iovcnt buffers I 
specified by the members of the iov array: iov[ 0], iov[ 1], ..., iov[iovcnt- 1]. iovcnt is valid if 
greater than 0 and less than or equal to |IOV_MAX}, defined in <limits.h>. 

Each iovec entry specifies the base address and length of an area in memory from which data 
should be written. The ivritev( ) function shall always write a complete area before proceeding to 
the next. 

lifildes refers to a regular file and all of the iov Jen members in the array pointed to by iov are 0, 
writev() shall return 0 and have no other effect. For other file types, the behavior is unspecified. 

If the sum of the iov Jen values is greater than {SSIZE_MAX}, the operation fails and no data is 
transferred. 

sio If the CLDSYNC bit has been set, write I/O operations on the file descriptor complete as defined 
by synchronized I/O data integrity completion. 

If the 0_SYNC bit has been set, write I/O operations on the file descriptor complete as defined 
by synchronized I/O file integrity completion. 

shm lifildes refers to a shared memory object, the result of the write( ) function is unspecified. 

tym lifildes refers to a typed memory object, the result of the write () function is unspecified. I 

man For regular files, no data transfer shall occur past the offset maximum established in the open I 

file description associated with fildes. I 

lifildes refers to a socket, zvrite( ) is equivalent to send( ) with no flags set. I 

RETURN VALUE 

xsi Upon successful completion, ivrite() and pzurite( ) shall return the number of bytes actually 
written to the file associated with fildes. This number shall never be greater than nbyte. 
Otherwise, -1 shall be returned and errno set to indicate the error. 
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xsi Upon successful completion, writev () shall return the number of bytes actually written. 

Otherwise, it shall return a value of -1, the file-pointer shall remain unchanged, and errno shall 
be set to indicate an error. 


ERRORS 

xsi The zvrite( ),pivrite( ), and writei ;()functions shall fail if: 


xsi 

MAN 


MAN 


MAN 


[EAGAIN] The 0_NONBLOCK flag is set for the file descriptor and the thread would be 

delayed in the write( ) operation. 

[EBADF] The fildes argument is not a valid file descriptor open for writing. 

[EFBIG] An attempt was made to write a file that exceeds the implementation- 

dependent maximum file size or the process' file size limit. 

[EFBIG] The file is a regular file, nbyte is greater than 0, and the starting position is 

greater than or equal to the offset maximum established in the open file 
description associated with fildes. 

[EINTR] The write operation was terminated due to the receipt of a signal, and no data 

was transferred. 

[EIO] A physical I/O error has occurred. 

[EIO] The process is a member of a background process group attempting to write 

to its controlling terminal, TOSTOP is set, the process is neither ignoring nor 
blocking SIGTTOU, and the process group of the process is orphaned. This 
error may also be returned under implementation-dependent conditions. 

[ENOSPC] There was no free space remaining on the device containing the file. 

[EPIPE] An attempt is made to write to a pipe or FIFO that is not open for reading by 

any process, or that only has one end open. A SIGPIPE signal shall also be sent 
to the thread. 


xsr [ERANGE] The transfer request size was outside the range supported by the STREAMS I 

file associated with fildes. 

The writev( ) function shall fail if: 

xsi [EINVAL] The sum of the iovjen values in the iov array would overflow an ssize_t 

xsi The write( ),pivrite( ), and zvritev( ) functions may fail if: 

xsr [EINVAL] The STREAM or multiplexer referenced by fildes is linked (directly or I 

indirectly) downstream from a multiplexer. 

man [ENXIO] A request was made of a nonexistent device, or the request was outside the 

capabilities of the device. 

xsr [ENXIO] A hangup occurred on the STREAM being written to. I 

xsr A write to a STREAMS file may fail if an error message has been received at the STREAM head. I 
In this case, errno is set to the value included in the error message. 

The writev () function may fail and set errno to: 

xsi [EINVAL] The iovcnt argument was less than or equal to 0, or greater than ]IOV_MAX}. 

xsi The pwrite{ ) function shall fail and the file pointer remain unchanged if: 
xsi [EINVAL] The offset argument is invalid. The value is negative. 


System Interfaces, Issue 6 


1543 



write() 


System Interfaces 


47019 

47020 

47021 

47022 

47023 

47024 

47025 

47026 

47027 

47028 

47029 

47030 

47031 

47032 

47033 

47034 

47035 

47036 

47037 

47038 

47039 

47040 

47041 

47042 

47043 

47044 

47045 

47046 

47047 

47048 

47049 

47050 

47051 

47052 

47053 

47054 

47055 

47056 

47057 

47058 

47059 


xsi [ESPIPE] fildes is associated with a pipe or FIFO. 

EXAMPLES 

Writing from a Buffer 

The following example writes data from the buffer pointed to by buf to the file associated with 
the file descriptor/d. 

tinclude <sys/types.h> 
tinclude <string.h> 

char buf[20] ; 
size_t nbytes; 
ssize_t bytes_written; 
int fd; 

strcpy (buf, "This is a testin''); 
nbytes = strlen (buf); 

bytes_written = write (fd, buf, nbytes); 


Writing Data from an Array 

The following example writes data from the buffers specified by members of the iov array to the 
file associated with the file descriptor/d. 

#include <sys/types.h> 

#include <sys/uio.h> 

#include <unistd.h> 

ssize_t bytes_written; 
int fd; 

char *buf0 = "short stringin"; 

char *bufl = "This is a longer stringin"; 

char *buf2 = "This is the longest string in this examplein"; 

int iovcnt; 

struct iovec iov[3]; 


iov [ 0 ] 

. iov_base 

= bufO; 


iov [ 0 ] 

. iov_len = 

strlen 

(buf 0) ; 

iov [ 1 ] 

. iov_base 

= bufl; 


iov [ 1 ] 

. iov_len = 

strlen 

(bufl); 

iov [ 2 ] 

. iov_base 

= buf2; 


iov [ 2 ] 

. iov_len = 

strlen 

(buf 2) ; 

iovcnt 

= sizeof 

(iov) / 

sizeof (struct iovec); 


bytes_written = writev (fd, iov, iovcnt); 
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47060 APPLICATION USAGE 

47061 None. 


47062 RATIONALE 

47063 See also the RATIONALE section in read(). 

47064 An attempt to write to a pipe or FIFO has several major characteristics: 

47065 • Atomicfnon-atomic : A write is atomic if the whole amount written in one operation is not 

47066 interleaved with data from any other process. This is useful when there are multiple writers 

47067 sending data to a single reader. Applications need to know how large a write request can be 

47068 expected to be performed atomically. This maximum is called {PIPE_BUF}. This volume of 

47069 IEEE Std. 1003.1-200x does not say whether write requests for more than {PIPE_BUF} bytes 

47070 are atomic, but requires that writes of {PIPE_BUF} or fewer bytes shall be atomic. 

47071 • Blocking/immediate: Blocking is only possible with 0_NONBLOCK clear. If there is enough 

47072 space for all the data requested to be written immediately, the implementation should do so. 

47073 Otherwise, the process may block; that is, pause until enough space is available for writing. 

47074 The effective size of a pipe or FIFO (the maximum amount that can be written in one 

47075 operation without blocking) may vary dynamically, depending on the implementation, so it 

47076 is not possible to specify a fixed value for it. 

47077 • Complete/partial/deferred: A write request: 

47078 int fildes; 

47079 size_t nbyte; 

47080 ssize_t ret; 

47081 char *buf; 

47082 ret = write (fildes, buf, nbyte) ; 


47083 may return: 

47084 complete ret=nbyte 

47085 partial ret<nbyte 


47086 

47087 

47088 

47089 


This shall never happen if nfn/te<{PIPE_BUF}. If it does happen (with 
n tn/f e > {PIPE_BUF}), this volume of IEEE Std. 1003.1-200x does not guarantee 
atomicity, even if ref<{PIPE_BUF}, because atomicity is guaranteed according 
to the amount requested, not the amount ivritten. 


47090 


deferred: ret-— 1, em70=[EAGAIN] 


47091 

47092 

47093 

47094 

47095 

47096 


This error indicates that a later request may succeed. It does not indicate that it 
shall succeed, even if /ihi/f<?<| PIPE_BUF}, because if no process reads from the 
pipe or FIFO, the write never succeeds. An application could usefully count the 
number of times [EAGAIN] is caused by a particular value of 
n byte > {PIPE_BUF} and perhaps do later writes with a smaller value, on the 
assumption that the effective size of the pipe may have decreased. 


47097 Partial and deferred writes are only possible with 0_NONBLOCK set. 


47098 The relations of these properties are shown in the following tables: 
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Write to a Pipe or FIFO with 0_NONBLOCK clear 

Immediately Writable: 

None Some nbyte 

t%fe<{PIPE_BUF} 

Atomic blocking Atomic blocking Atomic immediate 

nbyte nbyte nbyte 

n byte> {PIPE_BUF} 

Blocking nbyte Blocking nbyte Blocking nbyte 


If the 0_N0NBL0CK flag is clear, a write request shall block if the amount writable 
immediately is less than that requested. If the flag is set (by fcntl( )), a write request shall never 
block. 


Write to a Pipe or FIFO with 0_NONBLOCK set 

Immediately Writable: 

None Some nbyte 

77 fry f e< {PIPE_BUF} 

-1, [EAGAIN] -1, [EAGAIN] Atomic nbyte 

?7fryfe>{PIPE_BUF[ 

-1, [EAGAIN] <nbyte or -1, <nbyte or -1, 
[EAGAIN] [EAGAIN] 


There is no exception regarding partial writes when 0_N0NBL0CK is set. With the exception 
of writing to an empty pipe, this volume of IEEE Std. 1003.1-200x does not specify exactly when 
a partial write is performed since that would require specifying internal details of the 
implementation. Every application should be prepared to handle partial writes when 
0_NONBLOCK is set and the requested amount is greater than |PIPE_BUF}, just as every 
application should be prepared to handle partial writes on other kinds of file descriptors. 

The intent of forcing writing at least one byte if any can be written is to assure that each write 
makes progress if there is any room in the pipe. If the pipe is empty, [PIPE_BUF[ bytes must be 
written; if not, at least some progress must have been made. 

Where this volume of IEEE Std. 1003.1-200x requires -1 to be returned and errno set to 
[EAGAIN], most historical implementations return zero (with the 0_NDELAY flag set, which is 
the historical predecessor of 0_NONBLOCK, but is not itself in this volume of 
IEEE Std. 1003.1-200x). The error indications in this volume of IEEE Std. 1003.1-200x were chosen 
so that an application can distinguish these cases from end-of-file. While write () cannot receive 
an indication of end-of-file, read() can, and the two functions have similar return values. Also, 
some existing systems (for example. Eighth Edition) permit a write of zero bytes to mean that 
the reader should get an end-of-file indication; for those systems, a return value of zero from 
write( ) indicates a successful write of an end-of-file indication. 

Implementations are allowed, but not required, to perform error checking for write( ) requests of I 
zero bytes. I 

The concept of a {PIPE_MAX} limit (indicating the maximum number of bytes that can be I 
written to a pipe in a single operation) was considered, but rejected, because this concept would 
unnecessarily limit application writing. 

See also the discussion of 0_NONBLOCK in read (). 

Writes can be serialized with respect to other reads and writes. If a read() of file data can be 
proven (by any means) to occur after a ivrite{ ) of the data, it must reflect that ivrite( ), even if the 
calls are made by different processes. A similar requirement applies to multiple write operations 
to the same file position. This is needed to guarantee the propagation of data from write () calls 
to subsequent read() calls. This requirement is particularly significant for networked file 
systems, where some caching schemes violate these semantics. 
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47144 Note that this is specified in terms of read() and ivrite(). Additional calls, such as the common 

47145 readv () and writev(), would want to obey these semantics. A new "high-performance" write 

47146 analog that did not follow these serialization requirements would also be permitted by this 

47147 wording. This volume of IEEE Std. 1003.1-200x is also silent about any effects of application- 

47148 level caching (such as that done by stdio). 

47149 This volume of IEEE Std. 1003.1-200x does not specify the value of the file offset after an error is 

47150 returned; there are too many cases. For programming errors, such as [EBADF], the concept is 

47151 meaningless since no file is involved. For errors that are detected immediately, such as 

47152 [EAGAIN], clearly the pointer should not change. After an interrupt or hardware error, however, 

47153 an updated value would be very useful and is the behavior of many implementations. 

47154 This volume of IEEE Std. 1003.1-200x does not specify behavior of concurrent writes to a file 

47155 from multiple processes. Applications should use some form of concurrency control. 

47156 FUTURE DIRECTIONS 

47157 None. 

47158 SEE ALSO 

47159 chmod(), creat(), dnp(), fcntl(), getrlimit(), lseek(), open(), pipe(), ulimit(), the System Interface 

47160 Definitions volume of IEEE Std. 1003.1-200x, <limits.h>, <stropts.h>, <sys/uio.h>, <unistd.h> 

47161 CHANGE HISTORY 

47162 First released in Issue 1. 

47163 Derived from Issue 1 of the SVID. 

47164 Issue 4 

47165 The <unistd.h> header is added to the SYNOPSIS section. 

47166 Reference to ulimit in the DESCRIPTION is marked as an extension. 

47167 Reference to the process' file size limit and the ulimit () function are marked as extensions in the 

47168 description of the [EFBIG] error. 

47169 The [ENXIO] error is marked as an extension. 

47170 The APPLICATION USAGE section is removed. 

47171 The description of [EINTR] is amended. 

47172 The following changes are incorporated for alignment with the ISO POSIX-1 standard: 

47173 • The type of the argument buf is changed from char* to const void*, and the type of the 

47174 argument nbyte is changed from unsigned to size_t 

47175 • The DESCRIPTION is changed as follows: 

47176 — Writing at end-of-file is atomic. 

47177 — {SSIZE_MAX} is now used to determine the maximum value of nbyte. 

47178 — The consequences of activities after a call to the write( ) function are added. 

47179 — To improve clarity, the text describing operations on pipes or FIFOs when 

47180 0_N0NBL0CK is set is restructured. 

47181 Issue 4, Version 2 

47182 The following changes are incorporated for X/OPEN UNIX conformance: 

47183 • The zvritev () function is added to the SYNOPSIS. 
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47216 
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• The DESCRIPTION is updated to describe the writing of data to STREAMS files, an 
operational description of the ivritev () function is included, and a statement is added 
indicating that SIGXFSZ is generated if an attempted write operation would cause the 
maximum file size to be exceeded. 

• The RETURN VALUE section is updated to describe values returned by the ivritev ( ) function. 

• The ERRORS section has been restructured to describe errors that apply to both ivrite( ) and 
ivritev () apart from those that apply to ivritev () specifically. The [EIO], [ERANGE], and 
[EINVAL] errors are also added. 

Issue 5 

The DESCRIPTION is updated for alignment with the POSIX Realtime Extension and the POSIX 
Threads Extension. 

Large File Summit extensions are added. 

The pivrite( ) function is added. 

Issue 6 

The DESCRIPTION states that the ivrite() function does not block the thread. Previously this 
said "process" rather than "thread". 

The DESCRIPTION and ERRORS sections are updated so that references to STREAMS are I 
marked as part of the XSI STREAMS Option Group. I 

The following new requirements on POSIX implementations derive from alignment with the I 
Single UNIX Specification: 

• The DESCRIPTION now states that if ivrite() is interrupted by a signal after it has 
successfully written some data, it returns the number of bytes written. In earlier versions of 
this volume of IEEE Std. 1003.1-200x, it was optional whether ivrite( ) returned the number of 
bytes written, or whether it returned -1 with errno set to [EINTR], This is a FIPS requirement. 

• The following changes are made to support large files: 

— For regular files, no data transfer occurs past the offset maximum established in the open 
file description associated with th efildes. 

— A second [EFBIG] error condition is added. 

• The [EIO] error condition is added. 

• The [EPIPE] error condition is added for when a pipe has only one end open. 

• The [ENXIO] optional error condition is added. 

Text referring to sockets is added to the DESCRIPTION. I 

The following changes were made to align with the IEEE P1003.1a draft standard: I 

• The effect of reading zero bytes is clarified. I 

The DESCRIPTION is updated for alignment with IEEE Std. 1003.1j-2000 by specifying that I 
ivrite( ) results are unspecified for typed memory objects. I 
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47220 NAME 

47221 wscanf — convert formatted wide-character input 

47222 SYNOPSIS 

47223 #include <stdio.h> 

47224 #include <wchar.h> 

47225 int wscanf (const wchar_t * format, ... ) ; 

47226 DESCRIPTION 

47227 Refer to fwsconf(). 
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47228 NAME 

47229 yO, yl, yn — Bessel functions of the second kind 

47230 SYNOPSIS 

47231 xsi #include <math.h> 

47232 

47233 

47234 

47235 

47236 DESCRIPTION 

47237 The y0(), if! (), and yn () functions shall compute Bessel functions of x of the second kind of 

47238 orders 0,1, and n respectively. The application shall ensure that the value of x is positive. 

47239 An application wishing to check for error situations should set errno to 0 before calling y0(), 

47240 yl (), or yn (). If errno is non-zero on return, or the return value is NaN, an error has occurred. 

47241 RETURN VALUE 

47242 Upon successful completion, y0 (), yl( ), and yn () shall return the relevant Bessel value of x of 

47243 the second kind. 

47244 If x is NaN, NaN shall be returned and errno may be set to [EDOM], 

47245 If the x argument to y0 (), yl (), or yn () is negative, -HUGE_VAL or NaN shall be returned, and 

47246 errno may be set to [EDOM]. 

47247 If x is 0.0, -HUGE_VAL shall be returned and errno may be set to [ERANGE] or [EDOM]. 

47248 If the correct result would cause underflow, 0.0 shall be returned and errno may be set to 

47249 [ERANGE]. 

47250 If the correct result would cause overflow, -HUGE_VAL or 0.0 shall be returned and errno may 

47251 be set to [ERANGE]. 

47252 ERRORS 

47253 The y0( ), yl (), and yn () functions may fail if: 

47254 [EDOM] The value of x is negative or NaN. 

47255 [ERANGE] The value of x is too large in magnitude, or x is 0.0, or the correct result would 

47256 cause overflow or underflow. 

47257 No other errors shall occur. 

47258 EXAMPLES 

47259 None. 

47260 APPLICATION USAGE 

47261 None. 

47262 RATIONALE 

47263 None. 

47264 FUTURE DIRECTIONS 

47265 None. 

47266 SEE ALSO 

47267 isnan (), j0( ), the System Interface Definitions volume of IEEE Std. 1003.1-200x, <math.h> 


double yO(double x ); 
double yl(double x) ; 
double yn(int n, double x) ; 
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System Interfaces 


yOO 


CHANGE HISTORY 

First released in Issue 1. 

Derived from Issue 1 of the SVID. 


Issue 4 

References to matherr {) are removed. 

The RETURN VALUE and ERRORS sections are substantially rewritten to rationalize error 
handling in the mathematics functions. 


Issue 5 


Issue 6 


The DESCRIPTION is updated to indicate how an application should check for an error. This 
text was previously published in the APPLICATION USAGE section. 

The DESCRIPTION is updated to avoid use of the term "must” for application requirements. 
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47282 Notes to Reviewers 

47283 This section with side shading will not appear in the final copy. - Ed. 

47284 This chapter needs a complete overhaul. Volunteers are wanted to complete this task. 

47285 This chapter contains information to satisfy the recommendations of the TSG-1 Final Report: 

47286 • Section 4.1 describes perceived user requirements. 

47287 • Section 4.2 on page 1555 indicates how the facilities of this volume of IEEE Std. 1003.1-200x 

47288 satisfy those requirements. 

47289 • Section 4.3 on page 1559 offers guidance to writers of profiles on how the configurable 

47290 options, limits, and optional behavior of this volume of IEEE Std. 1003.1-200x should be cited 

47291 in profiles. 


47292 4.1 User Requirements 

47293 This section describes the user requirements as perceived by the developers of this volume of 

47294 IEEE Std. 1003.1-200x. The primary source for these requirements was an analysis of historical 

47295 practice in widespread use, as typified by the base documents listed in Chapter 1 on page 1. 

47296 This volume of IEEE Std. 1003.1-200x addresses the needs of users requiring open systems 

47297 solutions for source code portability of applications. It currently addresses: 

47298 • Multiprogramming and process management (creating processes, signaling, and so on) 

47299 • Access to files and directories in a hierarchy of file systems (opening, reading, writing, 

47300 deleting files, and so on) 

47301 • Access to asynchronous communications ports and other special devices 

47302 • Access to information about other users of the system 

47303 • Facilities supporting applications requiring bounded (realtime) response 

47304 This volume of IEEE Std. 1003.1-200x provides C-language functions. Thus, it also addresses the 

47305 following requirements: 

47306 • Specific requirements of the C binding 

47307 • Interaction of the C binding with the underlying I/O system 

47308 • Interaction of the C internationalization capabilities with the environment 

47309 Extensions in many areas are being prepared, and this chapter will be revised as these extensions 

47310 are completed. 

47311 The requirements of users of this volume of IEEE Std. 1003.1-200x can be summarized as a single 

47312 goal: application source portability. The requirements of the user are stated in terms of the 

47313 requirements of portability of applications. This in turn becomes a requirement for a 

47314 standardized set of syntax and semantics for operations commonly found on many operating 

47315 systems. 
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47316 The following sections list the perceived requirements for application portability. 

47317 4.1.1 Configuration Interrogation 

47318 An application must be able to determine whether and how certain optional features are 

47319 provided and to identify the system upon which it is running, so that it may appropriately adapt 

47320 to its environment. 

47321 4.1.2 Process Management 

47322 An application must be able to manage itself, either as a single process or as multiple processes. 

47323 Applications must be able to manage other processes when appropriate. 

47324 Applications must be able to identify, control, create, and delete processes, and there must be 

47325 communication of information between processes and to and from the system. 

47326 Applications must be able to use multiple flows of control with a process (threads) and 

47327 synchronize operations between these flows of control. 

47328 4.1.3 Access to Data 

47329 Applications must be able to operate on the data stored on the system, access it, and transmit it 

47330 to other applications. Information must have protection from unauthorized or accidental access 

47331 or modification. 

47332 Applications must have sufficient information to adapt to varying behaviors of the system. 

47333 4.1.4 Access to the Environment 

47334 Applications must be able to access the external environment to communicate their input and 

47335 results. 

47336 4.1.5 Access to Determinism and Performance Enhancements 

47337 Applications must have sufficient control of resource allocation to ensure the timeliness of 

47338 interactions with external objects. 

47339 4.1.6 Operating System-Dependent Profile 

47340 The capabilities of the operating system may make certain optional characteristics of the base 

47341 language in effect no longer optional, and this should be specified. 

47342 4.1.7 I/O Interaction 

47343 The interaction between the C language I/O subsystem and the I/O subsystem of this volume of 

47344 IEEE Std. 1003.1-200x must be specified. 
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47345 4.1.8 

47346 

47347 

47348 4.1.9 

47349 

47350 

47351 4.1.10 

47352 

47353 

47354 

47355 


47356 4.2 

47357 

47358 

47359 

47360 

47361 

47362 

47363 

47364 

47365 

47366 

47367 

47368 

47369 

47370 

47371 4.2.1 

47372 

47373 

47374 

47375 

47376 

47377 


Internationalization Interaction 

The effects of the environment of this volume of IEEE Std. 1003.1-200x on the 
internationalization facilities of the C language must be specified. 

C Language Extensions 

Certain functions in the C language must be extended to support the additional capabilities 
provided by this volume of IEEE Std. 1003.1-200x. 

Future Growth 

These requirements must be met to be able to create any useful set of applications. It is 
recognized that many interesting classes of applications cannot be written using only services 
meeting these requirements. Significant additions to this volume of IEEE Std. 1003.1-200x are 
being developed, and future versions will meet many of these additional requirements. 


Portability Capabilities 

This section describes the significant portability capabilities of this volume of 
IEEE Std. 1003.1-200x and indicates how the user requirements listed in Section 4.1 on page 1553 
are addressed. The capabilities are listed in the same format as the preceding user requirements; 
they are summarized below: 

• Configuration Interrogation 

• Process Management 

• Access to Data 

• Access to the Environment 

• Access to Determinism and Performance Enhancements 

• Operating System-Dependent Profile 

• I/O Interaction 

• Internationalization Interaction 

• C Language Extensions 

• Future Growth 

Configuration Interrogation 

The uname () operation provides basic identification of the system. The sysconf (), pathconf) ), and 
fpathconfi ) functions provide means to interrogate the implementation to determine how to 
adapt to the environment in which it is running. These values can be either static (indicating that 
all instances of the implementation have the same value) or dynamic (indicating that different 
instances of the implementation have the different values, or that the value may vary for other 
reasons, such as reconfiguration). 


System Interfaces, Issue 6 


1555 




Portability Capabilities 


Portability Considerations (Informative) 


47378 

47379 

47380 

47381 

47382 

47383 

47384 

47385 

47386 

47387 

47388 

47389 

47390 

47391 

47392 

47393 

47394 

47395 

47396 

47397 

47398 

47399 

47400 

47401 

47402 

47403 

47404 

47405 

47406 

47407 

47408 

47409 

47410 

47411 

47412 

47413 


Unsatisfied Requirements 

None directly. However, as new areas are added, there will be a need for additional capability in 
this area. 

4.2.2 Process Management 

The fork) ) and exec functions provide for the creation of new processes or the insertion of new 
applications into existing processes. The exit() and abort)) functions, defined by the ISOC 
standard, allow for the termination of a process by itself. The wait () and zvaitpid () functions 
allow one process to deal with the termination of another. 

The times)) function allows for basic measurement of times used by a process. Various 
functions, including getegid)), geteuid)), getgid)), getgrgid)) getgrnam)), getlogin)), getpid)), 
getppid)), getpwnam)), getpwuid)), getnid)), setgid)), setsid (), and setuid)), provide for access to 
the identifiers of processes and the identifiers and names of owners of processes (and files). 

The various functions operating on environment variables provide for communication of 
information (primarily user configurable defaults) from parent to child process. 

The operations on the current working directory control and interrogate the directory from 
which relative file name searches start. The umask)) function controls the default protections 
applied to files created by the process. 

The alarm)) and sleep)) operations allow the process to suspend until a timer has expired or to 
be notified when a period of time has elapsed. The time)) operation interrogates the current time 
and date. 

The signal mechanism provides for communication of events either from other processes or 
from the environment to the application, and the means for the application to control the effect 
of these events. The mechanism provides for external termination of a process and for a process 
to suspend until an event occurs. The mechanism also provides for a value to be associated with 
an event. 

The Job Control option provides a means to group processes and control them as groups, and to 
control their access to the function between the user and the system (the controlling terminal). It 
also provides the means to suspend and resume processes. 

The Process Scheduling option provides control of the scheduling and priority of a process. 

The Message Passing option provides a means for XSI interprocess communication involving 
small amounts of data. 

The Memory Management facilities provide control of memory resources and for the sharing of 
memory. 

The Threads facilities provide multiple flows of control with a process (threads), 
synchronization between threads, association of data with threads, and controlled cancelation of 
threads. 
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47415 
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Unsatisfied Requirements 

The following areas are currently under consideration: process resource limits, and 
checkpointing and restarting of processes. 

Access to Data 

The open(), close)), and pipe () functions provide for access to files and data. Such files may be 
classical files, interprocess data channels (pipes), or devices. Additional type of objects in the file 
system are permitted and are being contemplated for standardization. 

The access)), clmiod)), clioivn)), chip)), dup2)), fchmod)), fcntl)), fstat)), /truncate)), stat)), and 
utime)) functions allow for control and interrogation of file and file-related objects, and their 
ownership, protections, and timestamps. 

The Iseek)), read)), and write)) functions provide for data transfer from the application to files (in 
all their forms). 

The closedir)), link)), mkdir)), opendir)), readdir)), rename)), rmdir)), rewinddir)), and unlink)) 
functions provide for a complete set of operations on directories. Directories can arbitrarily 
contain other directories, and a single file can be mentioned in more than one directory. 

The file-locking mechanism provides for advisory locking (protection during transactions) of 
ranges of bytes (in effect, records) in a file. 

The pathconf)) and fpathconf)) functions provide for enquiry as to the behavior of the system 
where variability is permitted. Since this can vary with the location of the file, the enquiry 
includes a proposed location. 

The Synchronized Input and Output option provides for assured commitment of data to media. 

The Asynchronous Input and Output option provides for initiation and control of asynchronous 
data transfers. 

Unsatisfied Requirements 

The following areas are currently under consideration: control of accessibility to file types 
(which may be remote) with reduced semantics. 

Access to the Environment 

The operations and types in the System Interface Definitions volume of IEEE Std. 1003.1-200x, I 
Chapter 11, General Terminal Interface are provided for access to asynchronous serial devices. I 
The primary intended use for these is the controlling terminal for the application (the interaction 
point between the user and the system). They are general enough to be used to control any 
asynchronous serial device. The functions are also general enough to be used with many other 
device types as a user interface when some emulation is provided. 

Less detailed access is provided for other device types, but in many instances an application 
need not know whether an object in the file system is a device or a file to operate correctly. 
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Unsatisfied Requirements 

Detailed control of common device classes, specifically magnetic tape, is not provided. 

Bounded (Realtime) Response 

The Realtime Signals Extension provides queued signals and the prioritization of the handling of 
signals. The SCHED_FIFO and SCHED_RR scheduling policies provide control over processor 
allocation. The Semaphores option provides high-performance synchronization. The Memory 
Management functions provide memory locking for control of memory allocation, file mapping 
for high-performance, and shared memory for high-performance XSI interprocess 
communication. The Message Passing option provides for XSI interprocess communication 
without being dependent on shared memory. 

Unsatisfied Requirements 

A function to provide performance advice on file allocation and transfers is being developed. 

Operating System-Dependent Profile 

This volume of IEEE Std. 1003.1-200x makes no distinction between text and binary files. The 
values of EXIT_SUCCESS and EXIT_FAILURE are further defined. 

Unsatisfied Requirements 

None known, but the ISO C standard may contain some additional options that could be 
specified. 

I/O Interaction 

This volume of IEEE Std. 1003.1-200x defines how each of the ISO C standard stdio functions 
interact with the POSIX.l operations, typically specifying the behavior in terms of POSIX.l 
operations. 

Unsatisfied Requirements 

None. 

Internationalization Interaction 

The POSIX.l environment operations provide a means to define the environment for setlocale() 
and time functions such as ctime (). These functions then become fully specified in the POSIX.l 
environment. An additional function to set the time conversion is provided in tzset (). 

Unsatisfied Requirements 

See Section 4.2.10 on page 1559. 
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4.2.9 C Language Extensions 

The setjmp () and longjmp () functions are not defined to be cognizant of the signal masks defined 
for POSIX.l. The sigsetjmp () and siglongjmp() functions are provided to fill this gap. 

Unsatisfied Requirements 

None. 

4.2.10 Future Growth 

It is arguable whether or not all functionality to support applications is potentially within the 
scope of this volume of IEEE Std. 1003.1-200x. As a simple matter of practicality, it cannot be. 
Areas such as general networking, graphics, application domain-specific functionality, 
windowing, and so on, should be in unique standards. As such, they are properly "Unsatisfied 
Requirements" in terms of providing fully portable applications, but ones which are outside the 
scope of this volume of IEEE Std. 1003.1-200x. 

However, certain broad areas that are applicable are currently under consideration. 

• Security: All the functionality provided in this volume of IEEE Std. 1003.1-200x is subject to 
additional constraints when high levels of security are required. Additional functionality 
and constraints are now being investigated. 

• Internationalization: Only a small fraction of the requirements for writing applications that 
operate properly across varying cultures have been met. Much of this belongs in the 
underlying language, but some properly belongs in this volume of IEEE Std. 1003.1-200x, 
once consensus on the specific solutions can be reached. 


4.3 Profiling Considerations 

This section offers guidance to writers of profiles on how the configurable options, limits, and 
optional behavior of this volume of IEEE Std. 1003.1-200x should be cited in profiles. Profile 
writers should consult the general guidance in POSIX.O when writing POSIX Standardized 
Profiles. 

The information in this section is an inclusive list of the current features that should be 
considered by profile writers. Further subsetting of this volume of IEEE Std. 1003.1-200x, 
including the specification of behavior currently described as unspecified, undefined, 
implementation-dependent, or with the verbs "may" or "need not" , violates the intent of the 
developers of this volume of IEEE Std. 1003.1-200x and the guidelines of TR 10000-1. Work is in 
progress to identify application requirements (for example, embedded realtime systems) for 
subgroupings of the features. 

4.3.1 Configuration Options 

The options to support the various configuration options are listed in Profile writers should 
consult the following list and the comments concerning user requirements addressed by various 
POSIX.l components in Section 4.2 on page 1555. 

|NGROUPS_MAX} 

A non-zero value indicates that the implementation supports supplementary groups. 

This option is needed where there is a large amount of shared use of files, but where a 
certain amount of protection is needed. Many profiles 4 are known to require this option; it 
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should only be required if needed, but it should never be prohibited. 
POSIX_ASYNCHRONOUS_IO 

The system provides concurrent process execution and input and output transfers. 

This option was created to support historical systems that did not provide the feature. It 
should only be required if needed, but it should never be prohibited. 

POSIX_CHOWN_RESTRICTED 

The system restricts the right to "give away" files to other users. 

This option should be carefully investigated before it is required. Some applications expect 
that they can change the ownership of files in this way. It is provided where either security 
or system account requirements cause this ability to be a problem. It is also known to be 
specified in many profiles. 

POSIX_FSYNC 

The system supports file synchronization requests. 

This option was created to support historical systems that did not provide the feature. 
Applications that are expecting guaranteed completion of their input and output operations 
should require the _POSIX_SYNC_IO option. This option should never be prohibited. 

POSIX_JOB_CONTROL 

Job control facilities are mandatory in this volume of IEEE Std. 1003.1-200x. 

The option was created primarily to support historical systems that did not provide the 
feature. Many existing profiles now require it; it should only be required if needed, but it 
should never be prohibited. Most applications that use it can run when it is not present, 
although with a degraded level of user convenience. 

POSIX_MAPPED_FILES 

The system supports the mapping of regular files into the process address space. 

Both this option and the _POSIX_SHARED_MEMORY_OBJECTS option provide shared 
access to memory objects in the process address space. The functions defined under this 
option provide the functionality of existing practice for mapping regular files. This 
functionality was deemed unnecessary, if not inappropriate, for embedded systems 
applications and, hence, is provided under this option. It should only be required if needed, 
but it should never be prohibited. 

POSIX_MEMLOCK 

The system supports the locking of the address space. 

This option was created to support historical systems that did not provide the feature. It 
should only be required if needed, but it should never be prohibited. 

POSIX_MEMLOCK_RANGE 

The system supports the locking of specific ranges of the address space. 

For applications that have well-defined sections that need to be locked and others that do 
not, the standard supports an optional set of functions to lock or unlock a range of process 
addresses. The following are two reasons for having a means to lock down a specific range: 


. There are no formally approved profiles of this volume of IEEE Std. 1003.1-200x at the time of publication; the reference here is to 
various profiles generated by private bodies or governments. 
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1. An asynchronous event handler function that must respond to external events in a 
deterministic manner such that page faults cannot be tolerated. 

2. An input/output "buffer" area that is the target for direct-to-process I/O, and the 
overhead of implicit locking and unlocking for each I/O call cannot be tolerated. 

It should only be required if needed, but it should never be prohibited. 

POSIX_MEMORY_PROTECTION 

The system supports memory protection. 

The provision of this option typically imposes additional hardware requirements. It should 
never be prohibited. 

POSIX_PRIORITIZED_IO 

The system provides prioritization for input and output operations. 

The use of this option may interfere with the ability of the system to optimize input and 
output throughput. It should only be required if needed, but it should never be prohibited. 

POSIX_MESSAGE_PASSING 

The system supports the passing of messages between processes. 

This option was created to support historical systems that did not provide the feature. The 
functionality adds a high-performance XSI interprocess communication facility for local 
communication. It should only be required if needed, but it should never be prohibited. 

POSIX_PRIORITY_SCHEDULING 

The system provides priority-based process scheduling. 

Support of this option provides predictable scheduling behavior, allowing applications to 
determine the order in which processes that are ready to run are granted access to a 
processor. It should only be required if needed, but it should never be prohibited. 

posix_realtime_signals 

The system provides prioritized, queued signals with associated data values. 

This option was created to support historical systems that did not provide the features. It 
should only be required if needed, but it should never be prohibited. 

POSIX_SAVED_IDS 

The option was created primarily to support historical systems that did not provide the 
feature; typically the complement of the ones that at the time provided 
_POSIX JOB_CONTROL. Many existing profiles now require it; it should only be required 
if needed, but it should never be prohibited. Certain classes of applications rely on it for 
proper operation, and there is no alternative short of giving the application root privileges 
on most implementations that do not provide _POSIX_SAVED_IDS. 

POSIX_SEMAPHORES 

The system provides counting semaphores. 

This option was created to support historical systems that did not provide the feature. It 
should only be required if needed, but it should never be prohibited. 

POSIX_SHARED_MEMORY_OBJECTS 

The system supports the mapping of shared memory objects into the process address space. 

Both this option and the _POSIX_MAPPED_FILES option provide shared access to memory 
objects in the process address space. The functions defined under this option provide the 
functionality of existing practice for shared memory objects. This functionality was deemed 
appropriate for embedded systems applications and, hence, is provided under this option. It 
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should only be required if needed, but it should never be prohibited. 

POSIX_SYNCHRONIZED_IO 

The system supports guaranteed file synchronization. 

This option was created to support historical systems that did not provide the feature. 
Applications that are expecting guaranteed completion of their input and output operations 
should require this option, rather than the _POSIX_FSYNC option. It should only be 
required if needed, but it should never be prohibited. 

POSIX_THREADS 

The system supports multiple threads of control within a single process. 

This option was created to support historical systems that did not provide the feature. 
Applications written assuming a multi-threaded environment would be expected to require 
this option. It should only be required if needed, but it should never be prohibited. 

POSIX_THREADS_ATTR_STACKADDR 

The system supports specification of the stack address for a created thread. 

Applications may take advantage of support of this option for performance benefits, but 
dependence on this feature should be minimized. This option should never be prohibited. 

POSIX_THREADS_ATTR_STACKSIZE 

The system supports specification of the stack size for a created thread. 

Applications may require this option in order to ensure proper execution, but such usage 
limits portability and dependence on this feature should be minimized. It should only be 
required if needed, but it should never be prohibited. 

POSIX_THREADS_PRIORITY_SCHEDULING 

The system provides priority-based thread scheduling. 

Support of this option provides predictable scheduling behavior, allowing applications to 
determine the order in which threads that are ready to run are granted access to a processor. 
It should only be required if needed, but it should never be prohibited. 

POSIX_THREADS_PRIO_INHERIT 

The system provides mutual exclusion operations with priority inheritance. 

Support of this option provides predictable scheduling behavior, allowing applications to 
determine the order in which threads that are ready to run are granted access to a processor. 
It should only be required if needed, but it should never be prohibited. 

POSIX_THREADS_PRIO_PROTECT 

The system supports a priority ceiling emulation protocol for mutual exclusion operations. 

Support of this option provides predictable scheduling behavior, allowing applications to 
determine the order in which threads that are ready to run are granted access to a processor. 
It should only be required if needed, but it should never be prohibited. 

POSIX_THREADS_PROCESS_SHARED 

The system provides shared access among multiple processes to synchronization objects. 

This option was created to support historical systems that did not provide the feature. It 
should only be required if needed, but it should never be prohibited. 

POSIX_THREAD_SAFE_FUNCTIONS 

The system provides thread-safe versions of all of the POSIX.l functionality. 
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This option is required if the _POSIX_THREADS option is supported. This is a separate 
option because thread-safe functions are useful in implementations providing other 
mechanisms for concurrency. It should only be required if needed, but it should never be 
prohibited. 

_POSIX_TIMERS 

The system provides higher resolution clocks with multiple timers per process. 

This option was created to support historical systems that did not provide the features. This 
option is appropriate for applications requiring higher resolution timestamps or needing to 
control the timing of multiple activities. It should only be required if needed, but it should 
never be prohibited. 

Configurable Limits 

In general, the configurable limits in the System Interface Definitions volume of 
IEEE Std. 1003.1-200x, <limits.h> have been set to minimal values; many applications or 
implementations may require larger values. No profile can cite lower values. 

{AIO_LISTIO_M AX} 

The current minimum is likely to be inadequate for most applications. It is expected that 
this value will be increased by profiles requiring support for list input and output 
operations. 

{AICLMAX} 

The current minimum is likely to be inadequate for most applications. It is expected that 
this value will be increased by profiles requiring support for asynchronous input and 
output operations. 

{AIO_PRIO_DELTA_M AX} 

The functionality associated with this limit is needed only by sophisticated applications. It 
is not expected that this limit would need to be increased under a general-purpose profile. 

{ARG_MAX} 

The current minimum is likely to need to be increased for profiles, particularly as larger 
amounts of information are passed through the environment. Many implementations are 
believed to support larger values. 

{CHILD_MAX} 

The current minimum is suitable only for systems where a single user is not running 
applications in parallel. It is significantly too low for any system also requiring windows, 
and if _POSIX JOB_CONTROL is specified, it should be raised. 

{CLOCKRES_MIN} 

It is expected that profiles will require a finer granularity clock, perhaps as fine as 1 ps, 
represented by a value of 1,000 for this limit. 

{DELAYTIMER_MAX} 

It is believed that most implementations will provide larger values. 

{LINK_MAX} 

For most applications and usage, the current minimum is adequate. Many implementations 
have a much larger value, but this should not be used as a basis for raising the value unless 
the applications to be used require it. 

{LOGIN_NAME_MAX} 

This is not actually a limit, but an implementation parameter. No profile should impose a 
requirement on this value. 
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{MAX_CANON} 

For most purposes, the current minimum is adequate. Unless high-speed burst serial I 
devices are used, it should be left as is. I 

{MAXJNPUT) 

See {MAX_CANON}. 

{MQ_OPEN_MAX} 

The current minimum should be adequate for most profiles. 

{MQ_PRIO_MAX} 

The current minimum corresponds to the required number of process scheduling priorities. 
Many realtime practitioners believe that the number of message priority levels ought to be 
the same as the number of execution scheduling priorities. 

|NAME_MAX} 

Many implementations now support larger values, and many applications and users 
assume that larger names can be used. Many existing profiles also specify a larger value. 
Specifying this value will reduce the number of conforming implementations, although this 
may not be a significant consideration over time. Values greater than 255 should not be 
required. 

|NGROUPS_MAX} 

Non-zero values act as an option (as discussed in Section 4.3.1 on page 1559). The value 
selected might be typically 8 or larger. 

|OPEN_MAX) 

The historically common value for this has been 20. Many implementations support larger 
values. If applications that use larger values are anticipated, they should be specified. 

{PAGESIZE} 

This is not actually a limit, but an implementation parameter. No profile should impose a 
requirement on this value. 

|PATH_MAX} 

Historically, the minimum has been either 1,024 or indefinite, depending on the 
implementation. Few applications actually require values larger than 256, but some users 
may create file hierarchies that must be accessed with longer paths. This value should only 
be changed if there is a clear requirement. 

{PIPE_BUF} 

The current minimum is adequate for most applications. Historically, it has been larger. If 
applications that write single transactions larger than this are anticipated, it should be 
increased. Applications that write lines of text larger than this probably do not need it 
increased, as the text line is delimited by a newline. 

{POSIX_ VERSION) 

This is actually not a limit, but a standard version stamp. Generally, a profile should specify 
this standard by a name in the normative references section, not this value. 

|PTHREAD_DESTRUCTOR_ITERATIONS} 

It is unlikely that applications will need larger values to avoid loss of memory resources. 

{PTHRE AD_KE Y S_M AX} 

The current value should be adequate for most profiles. 

|PTHREAD_STACK_MIN} 

This should not be treated as an actual limit, but as an implementation parameter. No 
profile should impose a requirement on this value. 
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|PTHREAD_THREADS_MAX} 

It is believed that most implementations will provide larger values. 

|RTSIG_MAX} 

The current limit was chosen so that the set of POSIX.l signal numbers can fit within a 32- 
bit field. It is recognized that most existing implementations define many more signals than 
are specified in POSIX.l and, in fact, many implementations have already exceeded 32 
signals (including the "null signal" ). Support of j_POSIX_RTSIG_MAX} additional signals 
may push some implementations over the single 32-bit word line, but is unlikely to push 
any implementations that are already over that line beyond the 64 signal line. 

{SEM_NSEMS_MAX} 

The current value should be adequate for most profiles. 

{SEM_VALUE_MAX} 

The current value should be adequate for most profiles. 

{SSIZE_MAX} 

This limit reflects fundamental hardware characteristics (the size of an integer), and should 
not be specified unless it is clearly required. Extreme care should be taken to assure that any 
value that might be specified does not unnecessarily eliminate implementations because of 
accidents of hardware design. 

{STRE AM_M AX [ 

This limit is very closely related to {OPEN_MAX}. It should never be larger than 
{OPEN_MAX}, but could reasonably be smaller for application areas where most files are 
not accessed through stdio. Some implementations may limit {STREAM_MAX} to 20 but 
allow {OPEN_MAX} to be considerably larger. Such implementations should be allowed for 
if the applications permit. 

{TIMER_MAX} 

The current limit should be adequate for most profiles, but it may need to be larger for 
applications with a large number of asynchronous operations. 

{TTY_NAME_MAX} 

This is not actually a limit, but an implementation parameter. No profile should impose a 
requirement on this value. 

|TZNAME_MAX} 

The minimum has been historically adequate, but if longer timezone names are anticipated 
(particularly such values as UTC-1), this should be increased. 

4.3.3 Optional Behavior 

In this volume of IEEE Std. 1003.1-200x, there are no instances of the terms unspecified, 
undefined, implementation-dependent, or with the verbs "may" or "need not", that the 
developers of this volume of IEEE Std. 1003.1-200x anticipate or sanction as suitable for profile 
or test method citation. All of these are merely warnings to portable applications to avoid certain 
areas that can vary from system to system, and even over time on the same system. In many 
cases, these terms are used explicitly to support extensions, but profiles should not anticipate 
and require such extensions; future versions of this volume of IEEE Std. 1003.1-200x may do so. 
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